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Introduction 


This manual, Microsoft Windows Programmer’s Reference, Volume 3, describes 

the data types, messages, structures, macros, and printer escapes supported by the 

Microsoft® Windows™ operating system. In addition, dynamic data exchange 

(DDE) transactions, File Manager events, raster-operation codes, virtual-key . 
codes, and character tables are presented. 


Organization of This Manual 


Following are brief descriptions of the chapters and appendixes in this manual: 


Chapter 1, “Data Types,” describes the keywords that define the size and mean- 
ing of parameter and return values associated with the Windows application 
programming interface (API). | 


Chapter 2, “Messages,”’ describes formatted window messages, through which 
the Windows operating system communicates with applications, and notifica- 
tion messages, which notify a control’s parent window of actions that occur 
within the control. | | 


Chapter 3, “Structures,” defines the data structures associated with the func- 
tions that are part of the Windows API. | 


Chapter 4, “Macros,” describes the purpose and defines the parameters of mac- 
ros used to help manipulate data in Windows applications. 


Chapter 5, “Printer Escapes,” lists printer escapes for the Windows operating 
system. 


Chapter 6, “Dynamic Data Exchange Transactions,” describes the transactions 
sent by the Dynamic Data Exchange Management Library (DDEML) to an ap- 
plication’s dynamic data exchange (DDE) callback function. The transactions. 
notify the application of DDE activity that affects the application. 


Chapter 7, “File Manager Events and Messages,” provides descriptions of the 
events and menu commands File Manager sends to communicate with a File 

Manager extension dynamic-link library (DLL). The chapter also describes mes- | 
sages the DLL can send File Manager to retrieve information. 


Chapter 8, “Control Panel Messages,” lists the messages Control Panel sends to 
communicate with a Control Panel DLL. | 
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Chapter 9, “Common Dialog Box Messages,” describes the messages a com- 
mon dialog box can send to notify applications that the user has made or | 
changed a selection in the dialog box. 


Chapter 10, “Installable Driver Messages,” lists the messages the Windows 
operating system sends to notify installable drivers about specific events. 


Appendix A, “Binary and Ternary Raster-Operation Codes,” lists and describes 
the binary and ternary raster operations used by the graphics device interface 
(GDI). 


Appendix B, “Virtual-Key Codes,” shows the symbolic constant names, 
hexadecimal values, and keyboard equivalents for Windows virtual-key codes. 


Appendix C, “Character Tables,” illustrates the Windows character set, the 
Symbol character set, and the OEM character set used by the Windows operat- 
ing system. 


~ Document Conventions 


The following conventions are used throughout this manual to define syntax: 


Convention Meaning 


- Bold text Denotes a term or character to be typed literally, such as a 


resource-definition statement or function name (MENU or - — 
_CreateWindow), a command, or a command-line option | 
(/nod). You must type these terms exactly as shown. 


Italic text _ Denotes a placeholder or variable: You must provide the 


actual value. For example, the statement SetCursorPos(X, Y) 
requires you to substitute values for the X and Y parameters. 


Enclose optional parameters. 
Separates an either/or choice. 
Specifies that the preceding item may be repeated. 


BEGIN Represents an omitted portion of a sample application. 


END 
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In addition, certain text conventions are used to help you understand this material: 


Convention Meaning 
SMALL CAPITALS Indicate the names of keys, key sequences, and key combina- 
- tions—for example, ALT+SPACEBAR. 


FULL CAPITALS Indicate filenames and paths, type names and most structure 
names (which are also bold), and constants. 


monospace Sets off code examples and shows syntax spacing. 


‘é 
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Chapter 1 Data Types 3 


The data types in this chapter are keywords that define the size and meaning of 
parameters and return values associated with functions for the Microsoft Windows 
operating system, version 3.1. The following table contains character, integer, and 


Boolean types; pointer types; and handles. The character, integer, and Boolean 
types are common to most C compilers. Most of the pointer-type names begin 
with a prefix of P, N (for near pointers), or LP (for long pointers). A near pointer 
accesses data within the current data segment, and a long pointer contains a 32-bit 
segment:offset value. A Windows application uses a handle to refer to a resource 
that has been loaded into memory. Windows provides access to these resources 
through internally maintained tables that contain individual entries for each 
handle. Each entry in the handle table contains the address of the resource and a 
means of identifying the resource type. 


The Windows data types a are defined in the following table: 


Type Definition 

ABORTPROC 32-bit pointer to an AbortProc callback function. 

ATOM 16-bit value used as an atom handle. 

BOOL 16-bit Boolean value. 

BYTE 8-bit unsigned integer. Use LPBYTE to create 
32-bit pointers. Use PBYTE to create pointers 
that match the compiler memory model. 

CATCHBUF{[9] 18-byte buffer used by the Catch function. 

COLORREF 32-bit value used as a color value. 

DLGPROC 32-bit pointer to a dialog box procedure. 

DWORD 32-bit unsigned integer or a segment:offset 
address. Use LPD WORD to create 32-bit 
pointers. Use PDWORD to create pointers that 

| match the compiler memory model. 

FARPROC 32-bit pointer to a function. 

FNCALLBACK 32-bit value identifying the DdeCallback func- 
tion. Use PFNCALLBACK to create pointers 
that match the compiler memory model. 

FONTENUMPROC 32-bit pointer to an EnumFontsProc callback 

| function. 

GLOBALHANDLE 16-bit value used as a handle to a oe memory 

ie object. 

GNOTIFYPROC 32-bit pointer to a NotifyProc callback function. 

~ GOBJENUMPROC 32-bit pointer to a EnumObjectsProc callback 
| : one function. | 7 
- GRAYSTRINGPROC 32-bit pointer to a GrayStringProc callback 


function. 
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Type 
HANDLE 


HCURSOR 
HFILE 
HGDIOBJ 


HGLOBAL 
HHOOK 
HKEY 
HLOCAL 


HMODULE 
HOBJECT 
HWND | 
HOOKPROC 
HRSRC 
LHCLIENTDOC 


LHSERVER 
LHSERVERDOC 


LINEDDAPROC 
LOCALHANDLE 


LONG 
LPABC 
“LPARAM 


LPBI 


LPBITMAP 


Definition 


16-bit value used as a general handle. Use 
LPHANDLE to create 32-bit pointers. Use 
SPHANDLE to create 16-bit pointers. Use | 
PHANDLE to create pointers that match the 
compiler memory model. 

16-bit value used as a cursor handle. 

16-bit value used as a file handle. 

16-bit value used as a graphics device interface 
(GDI) object handle. 

16-bit value used as a handle to a global memory 
object. 

32-bit value used as a hook handle. 

32-bit value used as a handle to a key in the regis- 
tration database. Use PHKEY to create 32-bit 
pointers. 


16-bit value used as a handle to a local memory 
object. 


16-bit value used as a module handle. 

16-bit value used as a handle to an OLE object. 
16-bit value used as a handle to a window. 
32-bit pointer to a hook procedure. 

16-bit value used as a resource handle. 

32-bit value used as a handle to an OLE client 
document. 

32-bit value used as a handle to an OLE server. 
32-bit value used as a handle to an OLE server 
document. 

32-bit pointer to a LineDDAProc callback func- 
tion. | 

16-bit value used as a handle to a local memory 
object. 

32-bit signed integer. 

32-bit pointer to an ABC structure. 

32-bit signed value passed as a parameter to a 
window procedure or callback function. 

32-bit pointer toa BANDINFOSTRUCT struc- 
ture. : 


32-bit pointer to a BITMAP structure. Use 
NPBITMAP to create 16-bit pointers. Use PBIT- 
MAP to create pointers that match the compiler 
memory model. 


Type 
LPBITMAPCOREHEADER 


LPBITMAPCOREINFO 


LPBITMAPFILEHEADER 


LPBITMAPINFO 


LPBITMAPINFOHEADER | 


LPCATCHBUF 
LPCBT_CREATEWND 


LPCHOOSECOLOR 
LPCHOOSEFONT 
LPCLIENTCREATESTRUCT 


LPCOMPAREITEMSTRUCT 
~ LPCPLINFO 


LPCREATESTRUCT 
_ LPCSTR 
LPCTLINFO 


LPCTLSTYLE | 


LPDCB 
LPDEBUGHOOKINFO 
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Definition 


32-bit pointer to a BITMAPCOREHEADER 
structure. Use PPITMAPCOREHEADER to 
create pointers that match the compiler memory 
model. 

32-bit pointer to a BITMAPCOREINFO struc- 
ture. Use PBITMAPCOREINFO to create point- 
ers that match the compiler memory model. 

32-bit pointer to a BITMAPFILEHEADER 
structure. Use PBITMAPFILEHEADER to 
create pointers that match the compiler memory 
model. 

32-bit pointer to a BITMAPINFO structure. Use 
PBITMAPINFO to create pointers that match 
the compiler memory model.. 

32-bit pointer to a BITMAPINFOHEADER 
structure. Use PBITMAPINFOHEADER to 
create pointers that match the compiler memory 
model. 

32-bit pointer to a CATCHBUF array. 


32-bit pointer to a CBT_CREATEWND struc- 
ture. | 
32-bit pointer to a CHOOSECOLOR structure. 
32-bit pointer to a CHOOSEFONT structure. 
32-bit pointer to a CLIENTCREATESTRUCT 
structure. 7 


32-bit pointer to a COMPAREITEMSTRUCT 
structure. Use PCOMPAREITEMSTRUCT to 
create pointers that match the compiler memory 
model. 

32-bit pointer to a CPLINFO structure. Use 
PCPLINFO to create pointers that match the 
compiler memory model. 


32-bit pointer to a CREATESTRUCT structure. 
32-bit pointer to a nonmodifiable character string. 
32-bit pointer to a CTLINFO structure. Use 


PCTLINFO to create pointers that match the 
compiler memory model. | 


32-bit pointer to a CTLSTYLE structure. Use. 
PCTLSTYLE to create pointers that match the 
compiler memory model. 

32-bit pointer to a DCB structure. 


32-bit pointer to a DEBUGHOOKINFO 


structure. — 


Microsoft Windows Programmer’s Reference 


Type 
LPDELETEITEMSTRUCT 


LPDEVMODE 


LPDEVNAMES 
LPDOCINFO 
LPDRAWITEMSTRUCT 


LPDRIVERINFOSTRUCT | 


LPDRVCONFIGINFO 


LPEVENTMSG 


LPDRIVERINFOSTRUCT 


LPFINDREPLACE 
LPFMS_GETDRIVEINFO 


LPFMS_GETFILESEL 


LPFMS_LOAD 
LPHANDLETABLE 


LPHELPWININFO 


LPINT 


LPKERNINGPAIR 


Definition 


32-bit pointer to a DELETEITEMSTRUCT 
structure. Use PPELETEITEMSTRUCT to 
create pointers that match the compiler memory 
model. 

32-bit pointer toa DEVMODE structure. Use 
NPDEVMODE to create 16-bit pointers. Use 
PDEVMODE to create pointers that match the 
compiler memory model. 

32-bit pointer to a DEVNAMES structure. 
32-bit pointer to a DOCINFO structure. 

32-bit pointer to a DRAWITEMSTRUCT struc- 
ture. Use PDP/RAWITEMSTRUCT to create 
pointers that match the compiler memory model. 
32-bit pointer to a DRIVERINFOSTRUCT 
structure. 

32-bit pointer to a DRVCONFIGINFO struc- 
ture. Use PDRVCONFIGINFO to create point- 
ers that match the compiler memory model. 
32-bit pointer toa EVENTMSG structure. Use 
NPEVENTMSG to create 16-bit pointers. Use 
PEVENTMSG to create pointers that match the 
compiler memory model. 

32-bit pointer to a DRIVERINFOSTRUCT 
structure. 


32-bit pointer to a FINDREPLACE structure. 
32-bit pointer to a FMS_ GETDRIVEINFO 
structure. | 3 

32-bit pointer to a FMS_GETFILESEL struc- 
ture. | | 
32-bit pointer toa FMS_LOAD structure. 
32-bit pointer to a HANDLETABLE structure. 


Use PHANDLETABLE to create pointers that 
match the compiler memory model. 

32-bit pointer toa HELPWININFO structure. 
Use PHELPWININFO to create pointers that 
match the compiler memory model. _ 

32-bit pointer to a 16-bit signed value. Use PINT 
to create pointers that match the compiler 
memory model. 


32-bit pointer to a KERNINGPAIR structure. 


Type 
LPLOGBRUSH 


LPLOGFONT 
LPLOGPALETTE 
- LPLOGPEN 


LPLONG 


LPMAT2 
LPMDICREATESTRUCT 


LPMEASUREITEMSTRUCT 


LPMETAFILEPICT 
LPMETARECORD 


LPMOUSEHOOKSTRUCT 


LPMSG 


_ LPNCCALCSIZE_ PARAMS 


LPNEWCPLINFO 
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Definition 


32-bit pointer to a LOGBRUSH structure. Use 
NPLOGBRUSH to create 16-bit pointers. Use 
PLOGBRUSH to create pointers that match the 
compiler memory model. 

32-bit pointer to a LOGFONT structure. Use 
NPLOGFONT to create 16-bit pointers. Use 
PLOGFONT to create pointers that match the 
compiler memory model. 

32-bit pointer to a LOGPALETTE structure. 

Use NPLOGPALETTE to create 16-bit point- 
ers. Use PLOGPALETTE to create pointers that 
match the compiler memory model. 3 
32-bit pointer to a LOGPEN structure. Use 
NPLOGPEN to create 16-bit pointers. Use __ 
PLOGPEN to create pointers that match the com- 
piler memory model. 7 
32-bit pointer to a 32-bit signed integer. Use 
PLONG to create pointers that match the com- 
piler memory model. 

32-bit pointer to a MAT2 structure. 


32-bit pointer to an MDICREATESTRUCT 
structure. 

32-bit pointer to a MEASUREITEMSTRUCT 
structure. Use PMEASUREITEMSTRUCT to 
create pointers that match the compiler memory 
model. 

32-bit pointer to a METAFILEPICT structure. 
32-bit pointer to a METARECORD structure. 
Use PMETARECORD to create pointers that 
match the compiler memory model. 

32-bit pointer to a MOUSEHOOKSTRUCT 
structure. | 

32-bit pointer to an MSG structure. Use NPMSG 
to create 16-bit pointers. Use PMSG to create 
pointers that match the compiler memory model. 
32-bit pointer to an NCCALCSIZE_ PARAMS 
structure. | os | 
32-bit pointer to an NEWCPLINEO structure. 
Use PNEWCPLINFO to create pointers that 
match the compiler memory model. 
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Type 
LPNEWTEXTMETRIC 


LPOFSTRUCT 


LPOLECLIENT 
LPOLECLIENTVTBL 
LPOLEOBJECT 
LPOLEOBJECTVTBL 
LPOLESERVER 
LPOLESERVERDOC 
LPOLESERVERDOCVTBL 


LPOLESERVERVTBL 
LPOLESTREAM 
LPOLESTREAMVTBL 
LPOLETARGETDEVICE 


LPOPENFILENA ME 
LPOUTLINETEXTMETRIC 


LPPAINTSTRUCT 


LPPALETTEENTRY 
LPPOINT 


LPPOINTFX 
LPPRINTDLG | 
LPRASTERIZER_STATUS 


LPRECT 


Definition 


32-bit pointer to a NEWTEXTMETRIC struc- 
ture. Use NPNEWTEXTMETRIC to create 

16-bit pointers. Use PREWTEXTMETRIC to 
create pointers that match the compiler memory 
model. | | 


32-bit pointer to an OFSTRUCT structure. Use 
NPOFSTRUCT to create 16-bit pointers. Use 
POFSTRUCT to create pointers that match the 
compiler memory model. 


32-bit pointer to OLECLIENT structure. 

32-bit pointer to OLECLIENTVTBL structure. 
32-bit pointer to OLEOBJECT structure. 

32-bit pointer to OLEOBJECTVTBL structure. 
32-bit pointer to OLESERVER structure. 

32-bit pointer to OLESERVERDOC structure. 


32-bit pointer to OLESERVERDOCVTBL 
structure. 


32-bit pointer to OLESERVERVTBL structure. 
32-bit pointer to OLESTREAM structure. | 
32-bit pointer to OLESTREAMVTBL structure. 
32-bit pointer to OLETARGETDEVICE struc- 
ture. 

32-bit pointer to OPENFILENAME structure. 
32-bit pointer to an OUTLINETEXTMETRIC 
structure. 


32-bit pointer to a PAINTSTRUCT structure. 
Use NPPAINTSTRUCT to create 16-bit point- 


ers. Use PPAINTSTRUCT to create pointers 


that match the compiler memory model. 

32-bit pointer to a PALETTEENTRY structure. 
32-bit pointer to a POINT structure. Use 
NPPOINT to create 16-bit pointers. Use 
PPOINT to create pointers that match the com- 
piler memory model. 

32-bit pointer to a POINTFX structure. 

32-bit pointer to a PRINTDLG structure. 

32-bit pointer to a RASTERIZER_STATUS 
structure. 
32-bit pointer to a RECT structure. Use 
NPRECT to create 16-bit pointers. Use PRECT 
to create pointers that match the compiler 
memory model. 


Type 
LPRGBQUAD | 
LPRGBTRIPLE 
LPSEGINFO 
LPSIZE 


LPSTR 


LPTEXTMETRIC 


LPTTPOLYCURVE 
LPTTPOLYGONHEADER 


LPVOID 
LPWINDOWPLACEMENT 


LPWINDOWPOS 
LPWNDCLASS 


LPWORD 


LRESULT 
MFENUMPROC 


NEARPROC_ 
OLECLIPFORMAT 
PATTERN 


PCONVCONTEXT 
PCONVINFO 
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Definition 


32-bit pointer to a RGBQUAD structure. 


32-bit pointer to a RGBTRIPLE structure. 
32-bit pointer to a SEGINFO structure. 


32-bit pointer to a SIZE structure. Use NPSIZE 
to create 16-bit pointers. Use PSIZE to create 
pointers that match the compiler memory model. 


32-bit pointer to a character string. Use NPSTR 


to create 16-bit pointers. Use PSTR to create 
pointers that match the compiler memory model. 
32-bit pointer to a TEXTMETRIC structure. 
Use NPTEXTMETRIC to create 16-bit point- 
ers. Use PTEXTMETRIC to create pointers that 
match the compiler memory model. 

32-bit pointer to a TTPOLYCURVE structure. 


32-bit pointer to a TTPOLYGONHEADER 
structure. | 

32-bit pointer to an unspecified type. 

32-bit pointer to a WINDOWPLACEMENT 
structure. Use PWINDOWPLACEMENT to 
create pointers that match the compiler memory 
model. 

32-bit pointer to a WINDOWPOS structure. 
32-bit pointer to a WNDCLASS structure. Use 
NPWNDCLASS to create 16-bit pointers. Use 
PWNDCLASS to create pointers that match the 
compiler memory model. 

32-bit pointer to a 16-bit unsigned value. Use 
PWORD to create pointers that match the com- 
piler memory model. 

32-bit signed value returned from a window pro- 
cedure or callback function. 

32-bit pointer to an EnumMetaFileProc call- 
back function. 

16-bit pointer to a function. 

16-bit value used as a standard clipboard format. 
Equivalent to the LOGBRUSH structure. Use 
LPPATTERN to create 32-bit pointers. Use 
NPPATTERN to create 16-bit pointers. Use 
PPATTERN to create pointers that match the 
compiler memory model. | 

32-bit pointer toa CONVCONTEXT structure. 


32-bit pointer to a CONVINFO structure. 
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Type 
PHSZPAIR 
PROPENUMPROC 


RSRCHDLRPROC 
TIMERPROC 
UINT 
WNDENUMPROC 


WNDPROC 
WORD 
WPARAM 


Definition 


32-bit pointer to a HSZPAIR structure. 


32-bit pointer to an EnumPropFixedProc or 
EnumPropMovableProc callback function. 


32-bit pointer to a LoadProc callback function. 
32-bit pointer to a TimerProc callback function. 
16-bit unsigned value. 


32-bit pointer to an EnumWindowsProc call-. 
back function. 


32-bit pointer to a window procedure. 
16-bit unsigned value. 


16-bit signed value passed as a parameter to a 
window procedure or callback function. 


Messages 


2.1 
aa 
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Chapter 2 Messages 13 


The Microsoft Windows operating system communicates with applications 
through formatted window messages. These messages are sent to an application’s 
window procedure for processing. 


Some messages return values that contain information about the success of the 
message or contain other data needed by an application. To obtain the return. 
value, the application must call the SendMessage function to send the message to 
a window. This function does not return until the message has been processed. 


If the application does not require the return value of the message, it can call the 
PostMessage function to send the message. This function places a message in a 
window’s application queue and then returns immediately. If a message does not 
have a return value, the application can use either function to send the e Messaee: un- 
less the message description indicates otherwise. 


A message consists of three parts: a message number, a word parameter, and a 
long parameter. Message numbers are identified by predefined message names. 
Each message name begins with letters that suggest the meaning or origin of the 
message. The word parameter and long parameter, named wParam and [Param re- 
spectively, contain values that depend on the message number. 


The [Param parameter often contains more than one type of information. For ex- 
ample, the high-order word may contain a handle to a window and the low-order 
word may contain an integer value. The HIWORD and LOWORD utility macros 
can be used to extract the high- and low-order words of the /Param parameter. 
The HIBYTE and LOBYTE utility macros can be used with HIWORD and 
LOWORD to access any of the bytes. Casting can also be used. 


Following are the four ranges of message numbers: 


Range Meaning 

0 through WM_USER - 1 Messages reserved for use by Windows. 
WM_USER through 0x7FFF Integer messages for use by applications. 
0x8000 through OxBFFF Messages reserved for use by Windows. 
OxCO000 through OxFFFF String messages for use by applications. 


Message numbers in the first range (O through WM_USER a 1) are defined by 
Windows. Values in this range that are not explicitly defined are reserved for 
future use by Windows. This chapter describes messages in this range. 


Message numbers in the second range (WM_USER through 0x7FFF) can be 
defined and used by an application to send messages within a private window 


class. Such predefined control classes as BUTTON, EDIT, LISTBOX, and 


COMBOBOX may use values in this range. Messages in this range should not be 
sent to other applications unless the applications have been designed to exchange 
messages and to attach the same meaning to the message numbers. 


14 BM_GETCHECK 


Message numbers in the third range (0x8000 through OxBFFF) are reserved for 
future use by Windows. 


Message numbers in the fourth range (OxC000 through OxFFFF) are defined at run 
time when an application calls the RegisterWindowMessage function to obtain a 
message number for a string. All applications that register the identical string can 
use the associated message number for exchanging messages with each other. The 
actual message number, however, is not a constant and cannot be assumed to be 
the same in different Windows sessions. 


2.1 Window Messages 
This section describes window messages. These messages are presented in alpha- 
betic order. 


BM_GETCHECK _ (x 


BM_GETCHECK 
wParam = Q; /* not used, must be zero */ 
]Param = QL; /* not used, must be zero */ 


An application sends a BM_GETCHECK message to retrieve the check state of a 


button. 
Parameters This message has no parameters. 
Return Value The return value from a button created with the BS_AUTOCHECKBOX, 


BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, 
BS_RADIOBUTTON, or BS_3STATE style may be one of the following values: 


Value Meaning » 

0 Button state is unchecked. 

1 | Button state is checked. 

2 Button state is indeterminate (applies only-if the button has the 


-BS_3STATE or BS_AUTO3STATE style). 


If the button has any other style, the return value is 0. 


BM_GETSTATE 15 


Example This example determines if the ID. MYCHECKBOxX control is currently checked: 
int checked; 


checked = (int) SendDigItemMessage(hwndDlg, ID_MYCHECKBOX, 
BM_GETCHECK, @, QL); 


See Also BM_GETSTATE, BM_SETCHECK 


BM_GETSTATE Bx 


BM_GETSTATE 
wParam = Q; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application sends a BM_GETSTATE message to retrieve the state of a button. 
Parameters This message has no parameters. 


Return Value The return value specifies the current state of the button. You can use the follow- 
ing masks to extract information about the state: 


Mask Description 


0x0003 Specifies the check state (radio buttons and check boxes only). A value of 0 
indicates the button is unchecked. A value of 1 indicates the button is 
checked. A radio button is checked when it contains a dot; a check box is 
checked when it contains an X. A value of 2 indicates the check state is in- 
determinate (3-state check boxes only). The state of a 3-state check box is 
indeterminate when it is grayed. 

0x0004 Specifies the highlight state. A nonzero value indicates that the button is 

_ highlighted. A button is highlighted when the user presses and holds the left 
mouse button. The highlighting is removed when the user releases the 
mouse button. ; | 

Ox0008 = Specifies the focus state. A nonzero value indicates that the button has the 
focus. 
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Example 


See Also 


BM_SETCHECK 


Parameters 


Return Value 
Comments 


Example 


See Also 


This example determines whether a button currently has the focus: 
define BFFOCUS 0x0008 
DWORD dwResult; 


dwResult = SendDlgItemMessage(hdlg, ID_MYBUTTON, BM_GETSTATE, @, @L); 
if (dwResult & BFFOCUS) 


/* button has the focus */ 


BM_GETCHECK, BM_SETSTATE 


BM_SETCHECK 
wParam = (WPARAM) fCheck; /* check state a / 
1Param = QL; /* not used, must be zero */ 


An application sends a BM_SETCHECK message to set the check state of a 
button. 


fCheck 
Value of wParam. Specifies the check state. This parameter can be one of the 
following values: 


Value Meaning 
0 Set the button state to unchecked. 
i Set the button state to checked. 
2 Set the button state to indeterminate. This value can be used only if the 


button has the BS_3STATE or BS_AUTO3STATE style. 


The return value is always zero. 
The BM_SETCHECK message has no effect on push buttons. 


This example places a dot inside a radio button: 


SendDigItemMessage(hdlg, ID.MYRADIOBUTTON, BM_SETCHECK, TRUE, @L); 


BM_GETCHECK, BM_GETSTATE, BM_SETSTATE 
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BM_SETSTATE 7 [2x | 


BM_SETSTATE = 
wParam = (WPARAM) fState; /* highlight state * / 
1Param = @L; /* not used, must be zero */ 


An application sends a BM_SETSTATE message to set the highlight state of a 
button. 


Parameters fState 
Value of wParam. Specifies whether the button is to be highlighted. A nonzero 
value highlights the button. A zero value removes any highlighting. 


Return Value The return value is always zero. 


Comments Highlighting affects the exterior of a button. It has no effect on the check state of a 
| radio button or check box. | 


A button is automatically highlighted when the user presses and holds the left 
mouse button. The highlighting is removed when the user releases the mouse 
button. 


Example This example highlights and then removes highlighting from a push button, simu- 
| lating the visual effect of a user clicking the button: 


SendDlgItemMessage(hdlg, ID_MYPUSHBUTTON, BM_SETSTATE, TRUE, Q@L); 
/* : : 

* Perform some action; then remove the highlighting, 

* thereby returning it to its normal state. 

* / 


sendDIgitemMessage(hdlg, -ID_MYPUSHBUTTON, BM_ SETSTATE, FALSE, QL); 


See Also BM_GETSTATE, BM _SETCHECK 
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BM_SETSTYLE [aa 


BM_SETSTYLE 
wParam = (WPARAM) LOWORD(dwStyle); /* style * / 
1Param = MAKELPARAM(fRedraw, @); /* redraw flag */ 


An application sends a BM_SETSTYLE message to change the style of a button. 


Parameters dwStyle | 
Value of wParam. Specifies the button style. For an explanation of button 
styles, see the following Comments section. 


fRedraw | 
Value of the low-order word of /Param. Specifies whether the button is to be 
redrawn. A value of TRUE redraws the button. A value of FALSE does not 
redraw the button. 


Return Value The return value is always zero. 
Comments | The following are the button styles: 
Value Meaning 
BS_3STATE | Creates a button that is the same as a check box, ex- | 


cept that the box can be grayed (dimmed) as well as 
checked. The grayed state typically is used to show 
that a check box has been disabled. 


BS_AUTO3STATE Creates a button that is the same as a three-state 
| check box, except that the box changes its state when 
the user selects it. The state cycles through checked, 
grayed, and normal. 


BS_AUTOCHECKBOX Creates a button that is the same as a check box, ex- 
| | cept that an X appears in the check box when the user 
_ selects the box; the X disappears (is cleared) the next 
time the user selects the box. 


BS_AUTORADIOBUTTON Creates a button that is the same as a radio button, 
except that when the user selects it, the button auto- 
matically highlights itself and clears (removes the 

: selection from) any other buttons in the same group. 
BS_CHECKBOX Creates a small square that has text displayed to its 
right (unless this style is combined with the 
| BS_LEFTTEXT style). 
BS_DEFPUSHBUTTON Creates a button that has a heavy black border. The 
: user can select this button by pressing the ENTER key. 
This style is useful for enabling the user to quickly 
select the most likely option (the default option). 


Example 
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Value Meaning 


BS_GROUPBOX | Creates a rectangle in which other buttons can be 
| grouped. Any text associated with this style is dis- 
played in the rectangle’s upper-left corner. 


BS_LEFTTEXT | Places text on the left side of the radio button or 
check box when combined with a radio button or 
check box style. | 


BS_OWNERDRAW Creates an owner-drawn button. The owner window 
| receives a WM_MEASUREITEM message when the 
button 1s created, and it receives a 
WM_DRAWITEM message when a visual aspect of 
the button has changed. The BS_OWNERDRAW 
style cannot be combined with any other button 


| styles. 

BS_PUSHBUTTON Creates a push button that posts a WM_COMMAND 
message to the owner window when the user selects 
the button. | 

BS_RADIOBUTTON Creates a small circle that has text displayed to its 


right (unless this style is combined with the 
BS_LEFTTEXT style). Radio buttons are usually 
used in groups of related but mutually exclusive 
choices. 


An application should not attempt to change a button’s Sipe fot example, ae 
ing a radio button to a check box). | 


This example sends a BM_SETSTYLE message to make a button become the de- 
fault push button: 7 


SendDIlgItemMessage(hdlg, ID_MYPUSHBUTTON, BM_SETSTYLE, 
(WPARAM) BS_DEFPUSHBUTTON, TRUE); 


CB_ADDSTRING ok 


CB_ADDSTRING 7 
wParam = Q; /* not used, must be zero */ 
1Param = (LPARAM) (LPCSTR) Ipsz; /* address of string to add */ 


An application sends a CB_ADDST RIN G message to add a string to the list box 


_ of a combo box. If the list box does not have the CBS_SORT style, the string is - 


added to the end of the list. Otherwise, the out # is inserted into the list and the list 
1S sorted. 
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Parameters Ipsz | 
Value of /Param. Points to the null-terminated string to be added. If the combo 
box was created with an owner-drawn style but without the 
CBS_HASSTRINGS style, the value of the /psz parameter is stored rather than 
the string it would otherwise point to. 


Return Value The return value is the zero-based index to the string in the list box. The return 
value is CB_ERR if an error occurs; the return value is CB_ERRSPACE if insuffi- 
cient space is available to store the new string. 


Comments If an owner-drawn combo box was created with the CBS_SORT style but not the 
CBS_HASSTRINGS style, the WM_COMPAREITEM message is sent one or 
more times to the owner of the Sone box so that the new item can be properly 
placed in the list box. 


To insert a string into a specific location within the list, use the 
CB_INSERTSTRING message. 


Example This example adds the string “my string” to a list box: 


DWORD dwIndex; 


dwiIndex = SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_ADDSTRING, @, (LPARAM) ((LPCSTR) "my string"™)); 


See Also CB_INSERTSTRING, WM_COMPAREITEM 


CB_DELETESTRING 


CB_DELETESTRING 
wParam = (WPARAM) index; /* item to delete * / 
1Param = QL; /* not used, must be zero */ 


An application sends a CB_DELETESTRING message to delete a string in the list 
box of a combo box. 


Parameters — index 
Value of wParam. Specifies the zero-based index of the string to delete. 


Return Value — The return value is a count of the strings remaining in the list. The return value is 
CB_ERR if the index parameter specifies an index greater than the number of 
items in the list. 


Comments 


Example 


See Also 


CB_DIR 


Parameters 
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If the combo box was created with an owner-drawn style but without the 
CBS_HASSTRINGS style, a WM_DELETEITEM message is sent to the owner 
of the combo box so that the application « can free any additional data associated 
with the item. 


This example deletes the first string in a combo box: 


( 


DWORD dwRemaining; 


dwRemaining = SendDlgItemMessage(hdlg, ID_ ESE OMPOR Ds 
CB_DELETESTRING, @, @L); 


WM_DELETEITEM 


CB_DIR 


wParam = (WPARAM) (UINT) uAttrs; /* file attributes */ 
TParam = (LPARAM) (LPCSTR) IpszFileSpec; /* address of filename */ 


An application sends a CB_DIR mess to add a list of Aienanes to the box 
of a combo box. | 


~ wAttrs 


Value of wParam. Specifies the attributes of the files to be added to the list 
~ box. It can be any combination of the following values: 


Value Meaning 


0x0000 ‘File can be read from or written to. 
~ 0x0001 File can be read from but not written to. 
0x0002 File is hidden and does not appear in a ee listing. 
~0x0004 ~—— File is a system file. 7 
0x0010 The name pointed to by the [pszFileSpec parameter specifies a directory. 
0x0020 __ File has been archived. 7 


— 0x4000° All drives that match the name specified by the IpszF ileSpec parameter 
are included. 
0x8000 Exclusive flag. If the exclusive flag is set, only files of the specified 


type are listed. Otherwise, files of the specified type are listed 1 in addi- 
- tion to files that do not match the specified type. 
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Return Value 


Example 


See Also 


CB_ FINDSTRING 


Parameters 


Return Value 


lpszFileSpec 
Value of /Param. Points to the null-terminated string that specifies the filename 
to add to the list. If the filename contains any wildéards (for example, *.*), all 
files that match and have the attributes specified ay the wAttrs parameter will be 
added to the list. 


The return value is the zero-based index of the last filename added to the list. The 
return value is CB_ERR if an error occurs. The return value is CB_ERRSPACE if 
insufficient space is available to store the new strings. 


_ This example adds the names of all available drives to a combo box: 


DWORD dwiIndexLastIitem; 


dwiIndexLastItem = SendDigItemMessage(hdlg, ID_MYCOMBOBOX, CB_DIR, 
Q@x4000 | @x8000, (LPARAM) ((LPCSTR) "*")); 


DigDirList 


CB_FINDSTRING 


wParam = (WPARAM) indexStart; /* item before start of search */ 
1Param = (LPARAM) (LPCSTR) IpszFind; /* address of prefix string a / 


An application sends a CB_FINDSTRING message to find the first string that con- 
tains the prefix specified in the list box of a combo box. 


indexStart 
Value of wParam. Specifies the zero-based index of the item before the first 
item to be searched. When the search reaches the bottom of the list box, it con- 
tinues from the top of the list box back to the item specified by the indexStart 
parameter. If indexStart is —1, the entire list box is searched from the Peeve: 


lpszFind 
Value of /Param. Points to the null-terminated string that contains the sets to 
search for. The search is not case-sensitive, so this string can contain any combi- 
nation of uppercase and lowercase letters. 


The return value is the zero-based index of the matching item, or it is CB_ERR if 
the search was unsuccessful. | 


Comments 


Example 


See Also 


CB_FINDSTRINGEXACT 23 


If the combo box’s style is owner-drawn but not CBS_HASSTRINGS and 
CBS_SORT, CB_FINDSTRING is used. If the styles are owner-drawn and 
CBS_SORT but not CBS_HASSTRINGS, WM_COMPAREITEM messages 
are sent. | 


This example searches for the string “my string” in a combo box and copies it, if 
found, to the szBuf buffer: 


char szBuf[2@]; 
DWORD dwiIndex; 


dwiIndex = SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, | 
CB_FINDSTRING, @, (LPARAM) ((LPCSTR) "my string”™)); 
if (dwiIndex != CB_ERR) 
SendDl gItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_GETLBTEXT, (WPARAM) dwIndex, (LPARAM) ((LPCSTR) szBuf)); 


CB_FINDSTRINGEXACT, CB_SETCURSEL 


CBLFINDSTRINGEXACT =— an 


Parameters 


Return Value 


~CB_FINDSTRINGEXACT 


wParam = (WPARAM) indexStart; ps item before start of search */ 
TParam = (LPARAM) (LPCSTR) IpszFind; /* address of prefix string « / 


An application sends a CB_FINDSTRINGEXACT message to find the first list | 


~ box string (in a combo box) that matches the string specified in the IpszF'ind 


parameter. 


indexStart 
Value of wParam. Specifies the zero-based index of the item before the first 
item to be searched. When the search reaches the bottom of the list box, it con- 
tinues from the top of the list box back to the item specified by the indexStart 
parameter. If indexStart is —1, the entire list box is searched from the beginning. 


lpszFind | 
Value of /Param. Points to the null-terminated string to search for. This string 
can contain a complete filename, including the extension. The search is not 
case-sensitive, so this string can contain any combination of uppercase and 
lowercase letters. 


The return valde is the zero-based index of the matching item, or itis CB_ERR if 
the search was unsuccessful. 
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Comments 


See Also 


If the combo box’s style is owner-drawn but not CBS_HASSTRINGS and 
CBS_SORT, CB_FINDSTRING is used. If the styles are owner-drawn and 
CBS_SORT but not CBS_HASSTRINGS, WM -COMPAREITEM messages 
are sent. 


CB_FINDSTRING, CB_SETCURSEL 


CB_GETCOUNT 


Parameters 


Return Value | 


Comments 


Example 


CB_GETCOUNT 
wParam = Q; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero */ 


An application sends a CB_GETCOUNT message to retrieve the number of items 
in the list box of a combo box. 


This message has no parameters. 
The return value is the number of items in the list box. 


The returned count is one greater than the index value of the last item (the index is 
zero-based). 


This example retrieves the number of items in a combo box: 


WORD cListItems; 


cListItems = (WORD) SendDlgItemMessage(hdlg, ID _MYCOMBOBOX, 
CB_GETCOUNT, 9, Q@); 


CB_GETCURSEL | 


CB_GETCURSEL | 
wParam = Q; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero */ 


An application sends a CB_GETCURSEL message to retrieve the index of the cur- 
rently selected item, if any, in the list box of a combo box. 


Parameters 


Return Value 


Example 


See Also 


CB_GETDROPPEDCONTROLRECT 25 


This message has no parameters. 


The return value is the zero-based index of the currently selected item, or it is 
CB_ERR if no item is selected. 


This example retrieves the index of the currently selected string in the list box of a 
combo box and then retrieves that string: 


char szBuf[20]; 
DWORD dwindex; 


dwIndex = SendDigItemMessage(hdlg, ID_MYCOMBOBOX, CB_GETCURSEL, 0, @); 
if (dwIndex != CB_ERR) 
SendDigItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_GETLBTEXT, (WPARAM) dwIndex, (LPARAM) ((LPCSTR) szBuf)); 


CB_SETCURSEL 


CB_GETDROPPEDCONTROLRECT aa] 


Parameters 


Return Value 


CB_GETDROPPEDCONTROLRECT | 
wParam = Q; /* not used, must be zero * / 
1Param = (LPARAM) (RECT FAR*) Iprc; /* address of RECT structure */ 


An application sends a CB_GETDROPPEDCONTROLRECT message to retrieve 
the screen coordinates of the visible (dropped-down) list box of a combo box. 


lprc 
Value of /Param. Points to the RECT structure that is to receive the coordi- 
nates. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


The return value is always CB_OKAY. 
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Example 


This example retrieves the bounding rectangle of the list box of a combo box: 


RECT rcl; 


SendDI gItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_GETDROPPEDCONTROLRECT, @, (DWORD) ((LPRECT) &rcl)); 


CB_GETDROPPEDSTATE - a] 


Parameters 
Return Value 


Example 


See Also 


CB_GETDROPPEDSTATE | 
wParam = @; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application sends a CB_GETDROPPEDSTATE message to determine whether 
the list box of a combo box is visible (dropped down). 


This message has no parameters. 
The return value is nonzero if the list box is visible; otherwise, it is zero. 


This example determines whether the list box of a combo box is visible: 
BOOL fDropped; | 


fDropped = (BOOL) SendDigItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_GETDROPPEDSTATE, @, QL); 


CB_SHOWDROPDOWN 


CB_GETEDITSEL — Pax | 


CB_GETEDITSEL 
wParam = @; /* not used, must be zero */ 
1}Param = QL; /* not used, must be zero */ 


An application sends aCB_GETEDITSEL message to retrieve the starting and 
ending character positions of the current selection in the edit control of a combo 


box. 


Parameters 


Return Value 


Example 


See Also 


CB_GETEXTENDEDUI 27 


This message has no parameters. 


The return value is a doubleword value that contains the starting position in the 
low-order word and the position of the first nonselected character after the end of 
the selection in the high-order word. 


This example retrieves the selection positions of the edit control of a combo box, 
and converts them into starting and ending positions: 


DWORD dwResult; 
WORD wStart, wEnd; 


dwResult = SendDlgItemMessage(hdlg, ID _MYCOMBOBOX, 
| CB_GETEDITSEL, 0, @L); 

LOWORD(dwResult); 

HIWORD(dwResult); 


wStart 
wEnd 


CB_SETEDITSEL 


CB_GETEXTENDEDUI [3.1 | 


Parameters 


Return Value 


Comments 


CB_GETEXTENDEDUI 
wParam = Q; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero */ 


An application sends a CB_GETEXTENDEDUI message to determine whether a 
combo box has the default user interface or the extended user interface. 


This message has no parameters. 


The return value is nonzero if the combo box has the extended user interface; 
otherwise, it 1s zero. 


The extended user interface differs from the default user interface in the following 
ways: | 


= Clicking the static control displays the list box (CBS_DROPDOWNLIST style 
only). . | 
= Pressing the DOWN ARROW key displays the list box (F4 is disabled). 


= Scrolling in the static control is disabled when the item list is not visible (arrow 
Keys are disabled). | | 
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Example | This example determines whether a combo box has the extended user interface: 
BOOL fExtended; 


~fExtended = (BOOL) SendDigItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_GETEXTENDEDUI, @, OL); 


See Also | CB_SETEXTENDEDUI 


CB_GETITEMDATA | 


CB_GETITEMDATA 
wParam = (WPARAM) index; /* item index * / 
1}Param = QL; /* not used, must be zero */ 


An application sends a CB_GETITEMDATA message to a combo box to retrieve 
the application-supplied doubleword value associated with the specified item in 
the combo box. (This is the value in the /Param parameter of a CB_SETITEM- 
DATA message.) 


Parameters index 
| Value of wParam. Specifies the zero-based index of the item. 


Return Value The return value is the doubleword value associated with the item, or it is 
CB_ERR if an error occurs. 


See Also _CB_SETITEMDATA 


CB_GETITEMHEIGHT gy 


CB. GETITEMHEIGHT 
wParam (WPARAM) index; /* item index | * / 
1Param QL; /* not used, must be zero */ 


An application sends a CB _GETITEMHEIGHT message to retrieve the height of 
— list items in a combo box. 


CB_GETLBTEXT 29 


Parameters index 
| Value of wParam. Specifies the component of the combo box whose height is 
to be retrieved. If the index parameter is —1, the height of the edit-control (or 
static-text) portion of the combo box is retrieved. If the combo box has the 
CBS_OWNERDRAWVARIABLE style, index specifies the zero-based index 
of the list item whose height is to be retrieved. Otherwise, index should be set 
to zero. 


Return Value The return value is the height, in pixels, of the list items in a combo box. The re- 
turn value is the height of the item specified by the index parameter if the combo 
box has the CBS_OWNERDRAWVARIABLE style. The return value is the 
height of the edit-control (or static-text) portion of the combo box if index is —1. 
The return value is CB_ERR if an error occurred. 


Example This example sends a CB_GETITEMHEIGHT message to retrieve the height of 
the list items in a combo box: 


LRESULT 1IrHeight; 


IrHeight = SendDigItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_GETITEMHEIGHT, 9, @L); 


See Also CB_SETITEMHEIGHT 


CB_GETLBTEXT ‘ 


CB_GETLBTEXT | | 
wParam = (WPARAM) index; /* item index a / 
1Param = (LPARAM) (LPCSTR) IpszBuffer; /* address oF buffer */ 


An application sends a CB_GETLBTEXT message to retrieve a string from the 
list box of a combo box. 


Parameters index 
Value of wParam. Specifies the zero-based index of the string to retrieve. 
[pszBuffer 
Value of JParam. Points to the buffer that receives the string. The buffer must 
have sufficient space for the string and a terminating null character. A | 
CB_GETLBTEXTLEN message can be sent before the CB_GETLBTEXT mes- 
sage to retrieve the length, in bytes, of the string. 
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Return Value The return value is the length of the string, in bytes, excluding the terminating null 
character. If the index parameter does not specuy a valid index, the return value is 
CB_ERR. 

Comments If the combo box was created with an owner-drawn style but without the 


CBS_HASSTRINGS style, the buffer pointed to by the lpszBuffer parameter of 
the message receives the doubleword value associated with the item. 


Example This example retrieves the length of the first item in the list box of a combo box, 
allocates sufficient memory for the string, and sends a CB_GETLBTEXT message 
to retrieve the string: 


DWORD cbItemString; 
PSTR pSZz; 


cbItemString = SendDigitemMessage(hdlg, ID_ PY COMBOROK: 
CB_GETLBTEXTLEN, @, @L); 
if (cbItemString != CB_ERR) { 
psz = (PSTR) LocalAlloc(LMEM_FIXED, (WORD) cbItemString); 
SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_GETLBTEXT, @, (LPARAM) ((LPCSTR) psz)); 


See Also CB_GETLBTEXTLEN 


CB_GETLBTEXTLEN ahs 


CB_GETLBTEXTLEN 
wParam = (WPARAM) index; /* item index * / 
]Param = @L; /* not used, must be zero */ 


An application sends a CB_GETLBTEXTLEN message to retrieve the length of a 
string in the list box of a combo box. 


Parameters index | | 
Value of wParam. Specifies the zero-based index of the string. 


Return Value The return value is the length of the string, in bytes, excluding the terminating null 
- character. If the index parameter does not specty a valid index, the return value is 
CB_ERR. | 


CB_INSERTSTRING 31 


Example This example retrieves the length of the first item in the list box of a combo box: 


DWORD cbItemString; 


cbItemString = SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_GETLBTEXTLEN, 90, @L); 


See Also CB_GETLBTEXT 


CB_INSERTSTRING 


CB_INSERTSTRING 
wParam = (WPARAM) index; /* item index | * / 
1Param (LPARAM) (LPCSTR) I1psz; /* address of string to insert */ 


An application sends a'CB _INSERTSTRING message to insert a string into the 
list box of a combo box. Unlike the CB_ADDSTRING message, the 
CB_INSERTSTRING message does not cause a list with the CBS_SORT style to. 
be sorted. 


Parameters index | 
‘Value of wParam. Specifies the zero-based index of the position at which to in- 
sert the string. If this parameter is —1, the string is added to the end of the list. © 

[psz 

Value of /Param. Points to the null-terminated string that is to be inserted. If 
the combo box was created with an owner-drawn style but without the 
CBS_HASSTRINGS style, the value of the /psz parameter is stored rather than 
the string it would otherwise point to. 


Return Value The return value is the index of the position at which the string was inserted. The | 
return value is CB_ERR if an error occurs. The return value is CB_ERRSPACE if 
insufficient space is available to store the new string. 


Example This example inserts the string “my string” into the third pesicn in the list box of 
a combo box: 
SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_INSERTSTRING, 2, (LPARAM) ((LPCSTR) “my string")); 


See Also CB_ADDSTRING 


32 CB_LIMITTEXT 


CB_LIMITTEXT ee | 


CB_LIMITTEXT 
wParam = (WPARAM) cchLimit; /* maximum number of characters */ 
1Param = @L; /* not used, must be zero * / 


An application sends a CB_LIMITTEXT message to limit the length of the text 
that the user may type in the edit control of a combo box. 


Parameters cchLimit 
Value of wParam. Specifies the length, in bytes, of the text the user can enter. 
If this parameter is zero, the text length is set to 65,535 bytes. 


Return Value The return value is 1 if the message is successful. If this message is sent to a 
combo box with the style CBS_DROPDOWNLIST, the return value is CB_ERR. 


Comments If the combo box does not have the style CBS_AUTOHSCROLL, setting the text 
limit to be larger than the size of the edit control has no effect. 


The CB_LIMITTEXT message limits only the text the user can enter. It has no ef- 
fect on any text already in the edit control when the message is sent, nor does it af- 
fect the length of the text copied to the edit control when a string in the list box is 
selected. 


Example This example limits the text of the edit control of a combo box to five characters: 


SendDigItemMessage(hdlg, ID_MYCOMBOBOX, CB_LIMITTEXT, 5, OL); 


CB_RESETCONTENT a 


CB_RESETCONTENT | 
wParam = Q; /* not used, must be zero */ 
Leave = OL; /* not used, must be zero */ 


An applicadon sends a CB _RESETCONTENT message to remove all items from 
the list box and edit control of a combo box. — 


Parameters This message has no parameters. 


Return Value The return value is always CB_OKAY. 


Comments 


Example 


See Also 


CB_SELECTSTRING 33 


If the combo box was created with an owner-drawn style but without the 
CBS_HASSTRINGS style, the owner of the combo box receives a 
WM_DELETEITEM message for each item in the combo box. 


This example removes all items from the list box and edit control of a combo box: 


SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, CB_RESETCONTENT, @, OL); 


WM_DELETEITEM 


CB_SELECTSTRING pois 


_ Parameters 


Return Value 


Comments | 


CB_SELECTSTRING | 
wParam = (WPARAM) indexStart; /* item before first selection */ 
1Param (LPARAM) (LPCSTR) IpszSelect; /* address of prefix string * / 


An application sends a CB_SELECTSTRING message to search for a string in the 
list box of a combo box and, if the string is found, to select the string in the list 
box and copy it to the edit control. 


indexStart a 
Value of wParam. Specifies the zero-based index of the item before the first 
item to be searched. When the search reaches the bottom of the list box, it con- 
tinues from the top of the list box back to the item specified by the indexStart 
parameter. If indexStart is —1, the entire list box is searched from the beginning. 


lpszSelect | 
Value of /Param. Points to the null-terminated string that contains the prefix to 
search for. The search is not case-sensitive, so this string can contain any combi- 
nation of uppercase and lowercase letters. 


The return value is the index of the selected item if the string was found. The re- 
turn value is CB_ERR and the current selection is not ier if the search was 


unsuccessful. 


_ A string is selected only if its initial characters (from the Starting point) match the 


characters in the prefix string. : | : 


If the combo box’s style is owner-drawn but not CBS _HASSTRINGS and 
CBS_SORT, CB_FINDSTRING is used. If the styles are owner-drawn and 
CBS_SORT but not CBS_HASSTRINGS, WM_ COMPAREITEM messages _ 


_ are sent. 


34 CB_SETCURSEL 


Example This example searches the entire list box of a combo box for the string “my string” 
| and, if the string is found, selects it: | 


DWORD dwIndexFoundString; 


dwiIndexFoundString = SendDigItemMessage(hdig, ID _MYCOMBOBOX, 
CB_SELECTSTRING, -1, (LPARAM) ((LPCSTR) “my string"™)); 


See Also _CB_FINDSTRING 


CB_SETCURSEL — 


CB_SETCURSEL 
wParam (WPARAM) index; /* item index * / 
1]Param OL; /* not used, must be zero */ 


An application sends a CB_SETCURSEL message to select a string in the list box 
of a combo box. If necessary, the list box scrolls the string into view (if the list 
box is visible). The text in the edit control of the combo box is changed to reflect 
the new selection. Any previous selection in the list box is removed. | 


Parameters index 
Value of wParam. Specifies the zero-based index of the string to select. If the 
index parameter is —1, any current selection in the list box is removed and the 
edit control is cleared. 


Return Value The return value is the index of the item selected if the message is successful. The 
return value is CB_ERR if the index parameter is greater than the number of items 
in the list or if index is set to —1 (which clears the selection). 


Example This example retrieves the number of items in the list box of a combo box and 
sends a CB_SETCURSEL message to select the last item in the list: 


WORD cListItems; 


cListItems = (WPARAM) SendDlgItemMessage(hdlg, 
om ID_MYCOMBOBOX, CB_GETCOUNT, @, @); 
SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, 
CB_SETCURSEL, 
cListItems - 1,  /* zero-based index, so subtract one from total */ 
OL); | : 


See Also CB_GETCURSEL, CB_FINDSTRING 


CB_SETEXTENDEDUI 35 


CB_SETEDITSEL 


Parameters 


- Return Value 


~ Comments 
Example 


See Also 


CB_SETEDITSEL 
wParam = Q; /* not used, must be zero */ 
1Param = MAKELPARAM(ichStart, ichEnd); /* start and end positions */ 


An aeaieaton sends a CB_SETEDITSEL mESSAbS to select characters in the edit 
control of a combo box. 


ichStart 
Value of the low-order word of /Param. Specifies the starting position. If this 
parameter is set to —1, the selection, if ye is removed. 


ichEnd 
Value of the high-order word of /Param. Specifies the ending position. If this 
parameter is set to —1, all text from the starting position to the last character in 
the edit control is selected. 


The return value is nonzero if the message is successful. It is CB_ERR if the mes- 
sage is sent to a combo box with the CBS_DROPDOWNLIST style. 


The positions are zero-based. To select the first character of the edit control, you 
specify a starting position of zero. The ending position is for the character just 
after the last character to select. For example, to select the first four characters of 
the edit control, you would use a starting position of 0 and an ending position of 4. 


This example selects the first four characters of the edit control of a combo box: 


SendDl gItemMessage(hdlg, ID.MYCOMBOBOX, 
CB_SETEDITSEL, @, MAKELONG(®, 4)); 


CB_GETEDITSEL 


CB_ SETEXTENDEDU ee ee 


CB_ SETEXTENDEDUL 7 te 
wParam (WPARAM) (BOOL) fExtended; /* extended UI flag * / 
TParam = @L; /* not used, must be zero */ 


An application sends a CB_SETEXTENDEDUI message to select either the de- 


fault user interface or the extended user interface for a combo box that has the 
CBS_DROPDOWN or CBS_DROPDOWNLIST style. 


. 


36 CB_SETITEMDATA 


Parameters fExtended | | | | 
Value of wParam. Specifies whether the combo box should use the extended 
user interface or the default user interface. A value of TRUE selects the ex- 
tended user interface; a value of FALSE selects the standard user interface. 


Return Value The return value is CB_OKAY if the operation is successful, or it is CB_ERR if 
an error occurred. 


Comments The extended user interface differs from the default user interface in the following 
ways: 


= Clicking the static control displays the list box (CBS_DROPDOWNLIST style 
only). | | 
= Pressing the DOWN ARROW key displays the list box (F4 is disabled). 


= Scrolling in the static control is disabled when the item list is not visible (the 
arrow keys are disabled). 


Example This example selects the extended user interface for a combo box: _ 
SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, CB_SETEXTENDEDUI, 
TRUE, @L); | 
See Also CB_GETEXTENDEDUI 


CB_SETITEMDATA 


CB_SETITEMDATA 
wParam = (WPARAM) index; /* jtem index */ 
1Param = (LPARAM) (DWORD) dwData; /* jtem data */ 


An application sends a CB_SETITEMDATA message to set the doubleword value 
associated with the specified item in a combo box. If the item is in an owner- 
drawn combo box created without the CBS_HASSTRINGS ‘style, this message re- 
places the doubleword value that was contained in the [Param parameter of the 
CB_ADDSTRING or CB_INSERTSTRING message that added the item to the 
combo box. | 


Parameters — index 
Value of wParam. Specifies the zero-based index to the item. 


dwData 
Value of /Param. Specifies the new value to be associated with the item. 


Return Value 


See Also 


CB_SETITEMHEIGHT =37 


The return value is CB_ERR if an error occurs. 


CB_ADDSTRING, CB_INSERTSTRING 


CB SETITEMHEIGHT - i, nia, a 


Parameters 


Return Value 


~ Comments 


Example 


See Also 


CB_SETITEMHEIGHT 
wParam = (WPARAM) index; /* item index */ 
1Param = (LPARAM) (int) height; /* item height */ 


An application sends a CB_SETITEMHEIGHT message to set the height of list 
items in a combo box or the height of the edit-control (or static-text) portion of a 
combo box. 


index 
Value of wParam. Specifies whether the height of list items or the height of the 
edit-control (or static-text) portion of the combo box is set. 


If the combo box has the CBS _OWNERDRAWVARIABLE style, the index 
parameter specifies the zero-based index of the list item whose height is to be 
set; otherwise, index must be zero and the height of all list items will be set. 


If index is —1, the height of the edit-control or static-text portion of the combo 
box is to be set. 


height | | ae 
— Value of the low-order word of lParam. Specifies the height, in pixels, of the 
combo box component identified by index. 


The return value is CB_ERR if the index or r height is invalid. 


The height of the edit-control (or static-text) portion of the combo box is set inde- 
pendently of the height of the list items. An application must ensure that the height 
of the edit-control (or static-text) portion isn’t smaller than the height of a particu- 
lar list box item. 


This example sends a CB _SETITEMHEIGHT message to set the ae of list 


items in a combo box: 


LPARAM IrHeight; 


sendDigItemMessage(hdlg, ID_MYCOMBOBOX, CB_SETITEMHEIGHT, 
Q, IrHeight); 


CB_GETITEMHEIGHT 


38  CB_SHOWDROPDOWN 


CB_SHOWDROPDOWN 


CB_ SHOWDROPDOWN 
wParam = (WPARAM) (BOOL) fShow; /* the show/hide flag * / 
1Param = @L; /* not used, must be zero * / 

= 
An application sends a CB_SHOWDROPDOWN message to show or hide the list 
box of a combo box that has the CBS_-_ DROPDOWN or CBS_DROPDOWNLIST 
style. 


Parameters fShow 7 


Value of wParam. Specifies whether the drop-down list box is to be shown or 
hidden. A value of TRUE shows the list box. A value of FALSE hides the list 


box. 
Return Value The return value is always nonzero. 
Comments This message has no effect on a combo box created with the CBS_SIMPLE style. 
| Example This example shows the list box of a combo box: 


SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, CB_SHOWDROPDOWN, TRUE, QOL); 


DM_GETDEFID 


DM_GETDEFID 
wParam = Q; /* not used, must be zero */ 
1}Param = @L; /* not used, must be zero */ 


_ An application sends a DM_GETDEFID message to get the identifier of the de- 
fault push button for a dialog box. 


Parameters This message has no parameters. 


Return Value The return value is a doubleword value. If the default push button has an identifier 
value, the high-order word contains DC_HASDEFID and the low-order word con- 
tains the identifier value. The return value is zero if the default push button does 
not have an identifier value. 


Example 


See Also. 


‘EM_CANUNDO 39 


This example gets the identifier of the default push button of a dialog box: 


DWORD dwResult; 
WORD idDefPushButton; 


dwResult = SendMessage(hdlg, DM_GETDEFID, @, QL); 


if (HIWORD(dwResult) == DC_HASDEFID) 
idDefPushButton = LOWORD(dwResult); 


DM_SETDEFID 


DM_SETDEFID ont eee 


Parameters 


Return Value 


DM_SETDEFID 
wIDPushBtn = wParam; /* identifier of new default push button */ 


An application sends a DM_SETDEFID message to change the identifier of the de 
fault push button for a dialog box. 


wIDPushBtn 
Value of wParam. Specifies the identifier of the push button that will be one 
the default. . 


The return value is always nonzero. 


-EM_CANUNDO [ax] 


Parameters 


Return Value 


EM_CANUNDO 
wParam = Q; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application sends an EM_CANUNDO message to icieaeine whether an edit- 


control operation can be undone. 
This message has no parameters. 


The return value is nonzero if the last edit operation can be undone, or it is zero if 
the last edit operation cannot be undone. 3 : 


40 EM_EMPTYUNDOBUFFER 


Example 


See Also 


This example sends an EM_CANUNDO message to determine whether the last 
edit-control operation can be undone and, if so, sends an EM_UNDO message to 
undo the last operation: 


if (SendDigitemMessage(hdlg, ID_MYEDITCONTROL, EM.CANUNDO, 0, OL)) 
SendDI gItemMessage(hdlg, ID_MYEDITCONTROL, EM_UNDO, @, QL); 


EM_UNDO 


EM EMPTYUNDOBUFFER 


Parameters 


Return Value 


Comments 


Example 


See Also 


EM. EMPTYUNDOBUFFER 
wParam = @; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero */ 


An application sends an EM_EMPTYUNDOBUFFER message to reset (clear) the 
undo flag of an edit control. The undo flag is set whenever an operation within the 
edit control can be undone. 


This message has no parameters. 
This message does not return a value. 


The undo flag is automatically cleared whenever the edit control receives a 
WM_SETTEXT or EM_SETHANDLE message. 


This example resets the undo flag of an edit control: 


SendDilgItemMessage(hdlg, ID_MYEDITCONTROL, EM_EMPTYUNDOBUFFER, @, QL); 


EM_CANUNDO, EM_SETHANDLE, EM_UNDO, WM_SETTEXT 


EM_FMTLINES 41 


EM_FMTLINES = a 


EM_FMTLINES 
wParam (WPARAM) (BOOL) fAddEOL; /* line break flag * / 
1Param OL; /* not used, must be zero */ 


An application sends an EM_FMTLINES message to set the inclusion of soft line 

break characters on or off within a multiline edit control. A soft line break consists 

of two carriage returns and a linefeed inserted at the end of a line that is broken be- 
cause of wordwrapping. 


This message is processed only by multiline edit controls. 


Parameters fAddEOL | | 
| Value of wParam. Specifies whether soft line break characters are to be in- 
serted. A value of TRUE inserts the characters; a value of FALSE removes 


them. 
Return Value The return value is identical to the fAddEOL parameter. 
Comments This message affects only the buffer returned by the EM_GETHANDLE message 


and the text returned by the WM_GETTEXT message. It has no effect on the dis- 
play of the text within the edit control. 


A line that ends with a hard line break is not affected by the EM_FMTLINES mes- 
sage. A hard line break consists of one carriage return and a linefeed. 


Example This example sends an EM_FMTLINES message to turn off soft line breaks, then 
allocates a buffer for the text, and then retrieves the text by sending a 
WM_GETTEXT message: 


WPARAM cbText; 
HGLOBAL hmem; 
LPSTR Ipstr; 


SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_FMTLINES, FALSE, @); 


cbText = (WPARAM) SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
WM_GETTEXTLENGTH, @, QL); 
cbText+t; © /* make room for the terminating null character */ 
hmem = (HGLOBAL) GlobalAlloc(GMEM_MOVEABLE, (DWORD) cbText); 
Ipstr = GlobalLock(hmem) ; = | 
SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, 
WM_GETTEXT, cbText, (LPARAM) lIpstr); 


See Also | EM_GETHANDLE, WM_GETTEXT 


42 EM_GETFIRSTVISIBLELINE 


EM_GETFIRSTVISIBLELINE eo ges 


EM_ GETFIRSTVISIBLELINE 
wParam = Q@; - /* not used, must be zero oi 
1Param = @L; /* not used, must be zero */. 


An application sends an EM_GETFIRSTVISIBLELINE message to determine the 
topmost visible line in an edit control. 


Parameters This message has no parameters. 


Return Value The return value is the zero-based index of the topmost visible line. For single-line 
edit controls, the return value is zero. 


Example | This example gets the index of the topmost visible line in an edit control: 
int FirstVis; 


FirstVis = (int) SendDlgItemMessage(hdlg, IDD_EDIT, 
EM_GETFIRSTVISIBLELINE, 0, @L); 


EM_GETHANDLE [2x] 


EM_GETHANDLE 
wParam 0; | /* not used, must be zero */ 
1Param OL; /* not used, must be zero */ 


An application sends an EM_GETHANDLE message to retrieve a handle to the 
memory currently allocated for a multiline edit control. The handle is a local 
memory handle and can be used by any of the functions that take a local memory 
handle as a parameter. 


This message is processed only by multiline edit controls. 

Parameters _ This message has no parameters. 

Return Value The return value is a local memory handle identifying the buffer that holds the con- 
tents of the edit control. If an error occurs, such as sending the message to a single- 


_ line edit control, the return value is zero. 


Comments An application can send this message to a multiline edit control in a dialog box 
only if it created the dialog box with the DS_LOCALEDIT style flag set. If the . 


EM_GETLINE 493 


DS_LOCALEDIT style is not set, the return value is still nonzero, but the return 
value will not be meaningful. 


Example This example sends an EM_GETHANDLE message to a multiline edit control and 
calls the LocalSize function to determine the current size of the edit control using 
the handle returned by the EM_GETHANDLE message: 


HANDLE hmemMle; 
WORD cbMle; 


hmemMle = (HLOCAL) SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_GETHANDLE, @, @L); | 
cbMle = LocalSize(hmemM1e); 


See Also EM_SETHANDLE 


EM_GETLINE [2x | 


EM_GETLINE 
wParam = (WPARAM) line; /* line number to retrieve * / 
1Param = (LPARAM) (LPSTR) Ipch; /* address of buffer for line */ 


An application sends an EM_GETLINE message to retrieve a line of text from an 
edit control. 


Parameters line 7 
| Value of wParam. Specifies the line number of the line to retrieve from a multi- 
line edit control. Line numbers are zero-based; a value of zero specifies the first 
line. This parameter is ignored by a single-line edit control. 


lpch | , 
Value of Param. Points to the buffer that receives a copy of the line. The first 
word of the buffer specifies the maximum number of bytes that can be copied © 
_ to the buffer. | 


Return Value The return value is the number of bytes actually copied. The return value is zero if 
| the line number specified by the line parameter is greater than the number of lines 


in the edit control. 


Comments The copied line does not contain a terminating null character. 


44 EM GETLINECOUNT 


Example | This example sets the maximum size of the buffer, sends an EM_GETLINE mes- _ 
sage to get the first line of the multiline edit control, and adds a terminating null 
character to the end of the retrieved line: 


unsigned char szBuf[128]; 
WORD cbText; 


*(WORD *) szBuf = sizeof(szBuf) - 1; /* sets the buffer size */ 
cbText = (WORD) SendDilgItemMessage(hdig, ID_MYEDITCONTROL, 


EM _GETLINE, 
Q, /* line number | * / 
(DWORD) (LPSTR) szBuf); ~  /* buffer address * / 
szBuf[cbText] = '\@'; /* terminating null character */ 
See Also EM_LINELENGTH, WM_GETTEXT 


EM_GETLINECOUNT aa] 


EM_GETLINECOUNT 
wParam = Q; /* not used, must be zero */ 
1Param = OL; /* not used, must be zero */ 


An application sends an EM_GETLINECOUNT message to retrieve the number 
of lines in a multiline edit control. 


This message is processed only by multiline edit controls. 
Parameters This message has no parameters. 


Return Value The return value is an integer containing the number of lines in the multiline edit 
control. If no text is in the edit control, the return value is 1. 


Example | This example sends an EM_GETLINECOUNT message to retrieve the number of 
lines in a multiline edit control and then sends an EM_LINESCROLL message to 
scroll the edit control so that the last line is displayed at the top of the edit control. 


int cLines; 


cLines = (int) SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, . 
EM_GETLINECOUNT, @, OL); © | 
SendDlgItemMessage(hdlg, ID _MYEDITCONTROL, 
EM_LINESCROLL, @, MAKELONG(cLines - 1, @)); 


See Also EM_GETLINE, EM_LINELENGTH 


EM_GETMODIFY 45 


EM_GETMODIFY ay] 


Parameters 


Return Value 


Comments 


Example 


See Also 


EM_GETMODIFY 7 
wParam = Q; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero * / 


An application sends an EM_GETMODIFY message to determine whether the 
contents of an edit control have been modified. 


_ This message has no parameters. — 


The return value is nonzero if the edit-control contents have been modified, or it is 
zero if the contents have remained unchanged. 


Windows maintains an internal flag indicating whether the contents of the edit con- 
trol have been changed. This flag is cleared when the edit control is first created; 
or an EM_SETMODIFY message can be sent to clear the flag. 


This example sends an EM_GETMODIFY message to determine whether the edit 
control has been modified and, if it has, retrieves the current contents of the edit 
control and clears the modification flag by sending an EM_SETMODIFY mes- 
sage: 


char szBuf[128]; 


if (SendDigItemMessage(hdlg, ID _MYEDITCONTROL, 
EM_GETMODIFY, @, @L)) { 
SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, 
WM_GETTEXT, sizeof(szBuf), (LPARAM) ((LPCSTR) szBuf)); 
SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_SETMODIFY, FALSE, @L); 


EM_SETMODIFY 
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EM_GETPASSWORDCHAR Oe a 


EM_GETPASSWORDCHAR 
wParam = Q; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero +*/ 


An application sends an EM_GETPASSWORDCHAR message to retrieve the 
password character displayed in an edit control when the user enters text. 


Parameters This message has no parameters. 


Return Value The return value specifies the character to be displayed in place of the character 
typed by the user. The return value is NULL if no password character exists. 


Comments If the edit control is created with the ES_PASSWORD style, the default password 
character is set to an asterisk (*). 


See Also EM_SETPASSWORDCHAR 


EM_GETRECT [2x | 


EM_GETRECT 
wParam = Q; : /* not used, must be zero */ 
TParam = (LPARAM) (RECT FAR*) Iprc; /* address of RECT structure */ 


An application sends an EM_GETRECT message to retrieve the formatting rect- 
angle of an edit control. The formatting rectangle is the limiting rectangle of the 
text. The limiting rectangle is independent of the size of the edit-control window. 


Parameters [prc 
: — Value of lParam. Points to the RECT structure that receives the formatting 
rectangle. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


Return Value The return value is not a meaningful value. 


Comments 


Example 


See Also 


EM_GETSEL 


Parameters 


Return Value 


Example 


See Also 


EM_GETSEL 47 


The formatting rectangle of a multiline edit control can be modified by the 
EM_SETRECT and EM_SETRECTNP messages. 


This example sends an EM_GETRECT message to retrieve the formatting 
rectangle of an edit control: 


RECT rcl; 


SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_GETRECT, @, (DWORD) ((LPRECT) &rcl)); 


EM_SETRECT 


[ 2.x | 


EM_GETSEL 
wParam = Q; /* not used, must be zero */ 
]Param = OL; /* not used, must be zero */ 


An application sends an EM_GETSEL message to get the starting and ending char- 
acter positions of the current selection in an edit control. 


This message has no parameters. 


The return value is a doubleword value that contains the starting position in the 
low-order word and the position of the first nonselected character after the end of 
the selection in the high-order word. 


This example gets the selection positions of an edit control and converts them into 
Starting and ending positions: 


DWORD dwResult; 
WORD wStart, wEnd; 


dwResult = SendDlgItemMessage(hdlg, ID_MYCOMBOBOX, EM_GETSEL, 0, OL); 


wStart = LOWORD(dwResult); 
wEnd = HIWORD(dwResult); 


EM_SETSEL 


48 EM_GETWORDBREAKPROC 


EM_GETWORDBREAKPROC [3.1 | 


EM_GETWORDBREAKPROC 
wParam = Q; /* not used, must be zero */ 
lParam = QL; /* not used, must be zero */ 


An application sends the EM_GETWORDBREAKPROC message to an edit con- 
trol to retrieve the current wordwrap function. 


Parameters This message has no parameters. 
Return Value The return value specifies the procedure-instance address of the application-de- 
| fined wordwrap function. The return value is NULL if no wordwrap function ex- 
ists. 
Comments A wordwrap function scans a text buffer (which contains text to be sent to the dis- 


play), looking for the first word that does not fit on the current display line. The 
wordwrap function places this word at the beginning of the next line on the dis- 
play. A wordwrap function defines at what point Windows should break a line of 
text for multiline edit controls, usually at a space character that separates two 
words. 


See Also EM_SETWORDBREAKPROC, MakeProclInstance, WordBreakProc 


EM_LIMITTEXT (4 4: mex 


EM_LIMITTEXT | 
wParam = (WPARAM) cchMax; /* text length * / 
1Param = @L; /* not used, must be zero */ 


An application sends an EM_LIMITTEXT message to limit’ the length of the text 
the user can enter into an edit control. 


_ Parameters cchMax | | 7 | 
Value of wParam. Specifies the length, in bytes, of the text the user can enter. 
If this parameter is zero, the text length is set to 65,535 bytes. 


Return Value This message does not return a value. 


EM_LINEFROMCHAR 49 


Comments The EM_LIMITTEXT message limits only the text the user can enter. It has no 
effect on any text already in the edit control when the message is sent, nor does it 
affect the length of text copied to the edit control by the WM_SETTEXT message. 


If an application uses the WM_SETTEXT message to place more text into an edit 
control than is specified in the EM_LIMITTEXT message, the user can edit the en- 
tire contents of the edit control. 


SeeAlso WM._ SETTEXT 


EM_LINEFROMCHAR © [ax] 


EM_LINEFROMCHAR 
wParam = (WPARAM) ich; /* character index * / 
1Param = QL;  /* not used, must be zero */ 


An application sends an EM_LINEFROMCHAR message to retrieve the line num- 
ber of the line that contains the specified character index. A character index is the | 
number of characters from the beginning of the edit control. 


This message is processed only by multiline edit controls. 


Parameters ich 
| Value of wParam. Specifies the character index of the character contained in 
the line whose number is to be retrieved. If the ich parameter is —1, either the 
line number of the current line (the line containing the caret) is retrieved or, if 
there is a selection, the line number of the line containing the beginning of the 
selection is retrieved. 


Return Value The return value is the zero-based line number of the line containing the character 
: index specified by ich. | 
Example 3 This example sends an EM_LINEFROMCHAR message to retrieve the line num- | 


ber of the current line in a multiline edit control: 


SendDilgItemMessage(hdlg, ID_MYEDITCONTROL, . 
- EM_LINEFROMCHAR, -1, QL); 


See Also EM_LINEINDEX 
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EM_LINEINDEX er 


EM_LINEINDEX 
wParam = (WPARAM) line; /* line number ef 
]Param = @L; | /* not used, must be zero */ 


An application sends an EM_LINEINDEX message to retrieve the character index 
of a line within a multiline edit control. The character index is the number of char- 
acters from the beginning of the edit control to the specified line. 


This message is processed only by multiline edit controls. 


Parameters Line 
Value of wParam. Specifies the zero-based line number. A value of —1 speci- 
fies the current line number (the line that contains the caret). 


Return Value _ The return value is the character index of the line specified in the line parameter, 
| or it is —1 if the specified line number is greater than the number of lines in the 
edit control. 
Example This example uses the EM_GETLINECOUNT message to retrieve the number of 


lines in an edit control and then uses EM_LINEINDEX to retrieve the character 
index for the last line in the edit control: 


WPARAM cLines, index; 


cLines = (WPARAM) SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_GETLINECOUNT, @, Q@L); 

index = (WPARAM) SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_LINEINDEX, cLines - 1, @L); 


See Also EM_LINEFROMCHAR 


EM_LINELENGTH ax] 


@ 


EM_LINELENGTH 
wParam = (WPARAM) ich; /* character index a / 
1Param = QL; /* not used, must be zero */ 


An application sends an EM_LINELENGTH message to retrieve the length ofa 
line in an edit control. 


EM_LINESCROLL a1 


Parameters ich | | 
| Value of wParam. Specifies the character index of a character in the line whose 
length is to be retrieved when EM_LINELENGTH is sent to a multiline edit 
control. If this parameter is —1, the message returns the number of unselected 
characters on lines containing selected characters. For example, if the selection 
extended from the fourth character of one line through the eighth character 
from the end of the next line, the return value would be 10 (three characters 

on the first line and seven on the next). 


When EM_LINELENGTH 1s sent to a single-line edit control, this parameter is 
ignored. 


Return Value The return value is the length, in bytes, of the line specified by the ich parameter 
| when an EM_LINELENGTH message is sent to a multiline edit control. The re- 
turn value is the length, in bytes, of the text in the edit control when an 
EM_LINELENGTH message is sent to a single-line edit control. 


Comments Use the EM_LINEINDEX message to retrieve a character index for a given line 
number within a multiline edit control. = 


See Also EM_LINEINDEX 


EM. LINESCROLL a 


EM_ LINESCROLL | . 
wParam = Q; /* not used, must be zero * / 
1Param = MAKELPARAM(dv, dh); /* lines and characters to scroll */ 


- An application sends an EM_LINESCROLL message to scroll the text of a multi- | 
line edit control. 


T his message is processed only by multiline edit controls. 


Parameters dv | 
| a Value of the low-order word of /Param. Specifies the number of lines to scroll 
vertically. | 


dh | | | or | | | 
- Value of the high-order word of /Param. Specifies the number of character posi- _ 

tions to scroll horizontally. This value is ignored if the edit control has either | 
the ES_RIGHT or ES_CENTER style. , ig 


02 EM_REPLACESEL 


Return Value The return value is nonzero if the message is sent to a multiline edit control, or it is 
zero if the message is sent to a single-line edit control. 


Comments The edit control does not scroll vertically past the last line of text in the edit con- 
| trol. If the current line plus the number of lines specified by the dv parameter 
exceeds the total number of lines in the edit control, the value is adjusted so that 
the last line of the edit control is scrolled to the top of the edit-control window. 


The EM_LINESCROLL message can be used to scroll horizontally past the last 
character of any line. 


Example This example sends an EM_LINESCROLL message to scroll the text in a multi-— 
line edit control vertically by five lines: 


SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_LINESCROLL, @, MAKELONG(5, @)); 


EM_REPLACESEL [2x | 


EM_REPLACESEL 
wParam = Q; : ; /* not used, must be zero */ 
1Param = (LPARAM) (LPCSTR) IpszReplace; /* address of new string */ 


An application sends an EM_REPLACESEL message to replace the current selec- 
tion in an edit control with the text specified by the /pszReplace parameter. 


Parameters IpszReplace 
Value of /Param. Points to a null-terminated string containing the replacement 
text. 
Return Value This message does not return a value. 
- Comments Use the EM_REPLACESEL message when you want to replace only a portion of 


the text in an edit control. If you want to replace all of the text, use the 
WM_SETTEXT message. 


If there is no current selection, the replacement text is inserted at the current cursor 
location. 


EM_SETHANDLE u3 


Example This example sets the selection to the beginning of the edit control and inserts the 
string “CN: | 


SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_SETSEL, @, MAKELONG(@, @)); 
SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, 
EM REPLACESEL, @, (LPARAM) ((LPCSTR) "C:\\")); 


See Also WM_SETTEXT 


EM_SETHANDLE ee 


EM_SETHANDLE 
wParam (WPARAM) (HLOCAL) hloc; /* handle of local memory object */ 
1Param OL; /* not used, must be zero * / 


An application sends an EM_SETHANDLE message to set the handle to the local 
memory that will be used by a multiline edit control. 


This message is processed only by multiline edit controls. 


Parameters hloc , 
| Value of wParam. Identifies the local memory. This handle must have been 
created by a previous call to the LocalAlloc function using the 
LMEM_MOVEABLE flag. The memory should contain a null-terminated 
string, or the first byte of the allocated memory should be set to zero. 


Return Value This message does not return a value. 


Comments _ Before an application sets anew memory handle, it should send an 
, EM_GETHANDLE message to retrieve the handle to the current memory buffer 
and should free that memory by using the LocalFree function. | 


| Sending an EM_SETHANDLE message clears the undo buffer (EM_CANUNDO 
returns zero) and the internal modification flag (EM_ Cee retums zero). 
The edit-control window is redrawn. 


An application can send this message to a multiline edit control in a dialog box 
only if it has created the dialog box with the DS_LOCALEDIT style flag set. 


04 EM 


Example 


See Also 


SETHANDLE 


This example frees the current memory for the edit control, allocates new 
memory, and reads up to BUF_SIZE bytes of a file into the allocated memory. It 
then sends an EM_SETHANDLE message to set the handle of the edit control to 
the new memory, effectively placing up to BUF_SIZE bytes of the file into the 
edit control. 


#tdefine BUF_SIZE 4 * 1024 


HANDLE hFile; 

OFSTRUCT ofs; 

HLOCAL hOldMem, hNewMem; 
PSTR pBuf; 

int cbRead; 


/* Get the handle to the old memory and free it. */ 


hOldMem = (HLOCAL) SendDigItemMessage(hdlg, 
ID_MYEDITCONTROL, EM_GETHANDLE, 0, OL); 
LocalFree(hOldMem) ; 


/* Allocate new memory and read the file into it. */ 


hNewMem = LocalAlloc( LMEM_MOVEABLE, BUF_SIZE); 

pBuf = LocalLock(hNewMem) ; 

hFile = OpenFile("test.txt", &ofs, OF_READ); 

cbRead = _lread(hFile, pBuf, BUF_SIZE); 

pBufLcbRead] = '\@'; /* terminating null character */ 
_Iclose(hFile); 


/* Adjust the buffer for the amount actually read in. */ 
LocalReAlloc(hNewMem, cbRead, @); 

/* Set the handle to the new buffer. */ 
LocalUnlock(hNewMem) ; 


SendDlgItemMessage(hdlg, ID _MYEDITCONTROL, 
EM_SETHANDLE, hNewMem, @L); 


EM CANUNDO, EM_GETHANDLE, EM_GETMODIFPY, LocalAlloc, 
LocalFree | 


EM_SETPASSWORDCHAR 99 


EM_SETMODIFY EH 


EM_SETMODIFY 
wParam = (WPARAM) (UINT) fModified; /* modification flag * / 
1Param OL; /* not used, must be zero */ 


An application sends an EM_SETMODIFY message to set or clear the modifica- 
tion flag for an edit control. The modification flag indicates whether the text 
within the edit control has been modified. It is automatically set whenever the user 
changes the text. An EM_GETMODIFY message can be sent to retrieve the value 
of the modification flag. | 


Parameters fModified 
Value of wParam. Specifies the new value for the modification flag. A value of 
TRUE indicates the text has been modified, and a value of FALSE indicates it 
has not been modified. 


Return Value _ This message does not return.a value. 


Example This example sends an EM_SETMODIFY message to clear the modification flag: 
SendDigItemMessage(hdlg, ID_MYEDITCONTROL, EM_SETMODIFY, FALSE, @L); 


See Also EM_GETMODIFY 


EM_SETPASSWORDCHAR  —— 


EM_SETPASSWORDCHAR é } | 
wParam = (WPARAM) (UINT) ch; /* character to display ¥*/ 
TParam = OL; | /* not used, must be zero */ 


An application sends an EM_SETPASSWORDCHAR message to set or remove a 
password character displayed in an edit control when the user types text. When a 
password character is set, that character is displayed for each character the user 


types. 


This message has no effect on a multiline edit control. 


Parameters | ch ; : a 
| Value of wParam. Specifies the character to be displayed in place of the charac- 
ter typed by the user. If the ch parameter is zero, the actual characters ee by © 
the user are displayed. con 


56 EM_SETREADONLY 


Return Value The return value is nonzero if the message is sent to an edit control. 


Comments When the EM_SETPASSWORDCHAR message is received by an edit control, 
the edit control redraws all visible characters by using the character specified by 
the ch parameter. 


If the edit control is created with the ES_PASSWORD style, the default 
password character is set to an asterisk (*). This style is removed if an 
EM_SETPASSWORDCHAR message is sent with the wParam peewee 
set to zero. 


Example This example sends an EM_SETPASSWORDCHAR message to set the password 
| character of an edit control to a question mark: 


SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_SETPASSWORDCHAR, (WORD) '?', @L); 


See Also EM_GETPASSWORDCHAR 


EM_SETREADONLY [3.1 | 


EM_SETREADONLY 
wParam = (WPARAM) (BOOL) fReadOnly; /* read-only flag * / 
1Param = @L; /* not used, must be zero */ 


An application sends an EM_SETREADONLY message to set the read- -only state 
of an edit control. 


Parameters fReadOnly 
Value of wParam. Specifies whether to set or remove the read-only state of the 
edit control. A value of TRUE sets the state to read-only; a value of FALSE 
sets the state to read/write. 


Return Value The return value is nonzero if the operation is successful, or it is zero if an error 
occurs. 
Comments When the state of an edit control is set to read-only, the user cannot change the 


text within the edit control. 


Example This example sets the state of an edit control to read-only: 


SendDl gItemMessage(hdlg, IDD_EDIT, —M_SETREADONLY, 
TRUE, QL); 


EM_SETRECT o7 


EM_SETRECT ra 


Parameters 


Return Value 


Comments 


EM_SETRECT 
wParam = Q; /* not used, must be zero */ 
]Param = (LPARAM) (const RECT FAR*) lprc; /* address of RECT — */ 


An application sends an EM_SETRECT message to set the formatting rectangle of 
a multiline edit control. The formatting rectangle is the limiting rectangle of the 
text. The limiting rectangle is independent of the size of the edit-control window. 
When the edit control is first created, the formatting rectangle is the same as the 
client area of the edit-control window. By using the EM_SETRECT message, an 
application can make the formatting rectangle larger or smaller than the edit- 
control window. | 


This message is processed only by multiline edit controls. 


lprc 
Value of /Param. Points to a RECT structure that specifies the new dimensions 
of the rectangle. The RECT structure has the following form: 


typedef struct tagRECT { /* rc. */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


This message does not return a value. 


The EM_SETRECT message causes the text of the edit control to be redrawn. To 


_ change the size of the formatting rectangle without redrawing the text, use the 


EM_SETRECTNP message. 


If the edit control does not have a ionzoneal scroll bar, and the formatting rect- 
angle is set to be larger than the edit-control window, lines of text exceeding the 


_ width of the edit-control window (but smaller than the width of the formatting 


rectangle) are clipped instead of wrapped. 


If the edit control contains a border, the formatting rectangle is reduced by the size 


of the border. If you are adjusting the rectangle returned by an EM_GETRECT 
message, you must remove the size of the border before using the rectangle with 
the EM_SETRECT message. 


38 EM_SETRECTNP 


Example 


See Also 


This example retrieves the current formatting rectangle for a multiline edit control, 
removes the border width dimensions, and sets the right border to 32767 so that all 
text sent to the edit control is clipped rather than wrapped if it exceeds the width of 
the edit-control window. The example then sends an EM_SETRECT message to 
set the new formatting rectangle. 


RECT rect; 


-SendDIgItemMessage(hdlg, ID.MYEDITCONTROL, 


EM_GETRECT, @, (LPARAM) (RECT FAR*) &rect); 


rect.left = Q; /* remove border width */ 
rect.right = 32767; /* clip all lines * / 
rect.bottom += rect. top; /* remove border height */ 
rect.top = @; /* remove border height */ 


SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_SETRECT, @, (LPARAM) (RECT FAR*) &rect); 


EM_GETRECT, EM_SETRECTNP, MoveWindow 


EM_SETRECTNP a ax] 


EM_ SETRECTNP. S; 
wParam = @; /* not used, must be zero | 
1]Param = (LPARAM) (const RECT FAR*) Iprc; /* address of RECT a / 


An application sends an EM_SETRECTNP message to set the formatting rect- 
angle of a multiline edit control. The formatting rectangle is the limiting rectangle 
of the text. The limiting rectangle is independent of the size of the edit-control win- 
dow. When the edit control is first created, the formatting rectangle is the same as 
the client area of the edit-control window. By using the EM_SETRECTNP mes- 
sage, an application can make the formatting Keane larger or smaller than the 
edit-control window. : 


The EM_SETRECTNP message is identical to the EM_SETRECT message, ex- 
cept that the edit-control window is not redrawn. 


This message is processed only by multiline edit controls. 


EM_SETSEL 59 


Parameters 


Return Value 


See Also | 


lprc 
Value of /Param. Points to a RECT structure that specifies the new dimensions 
of the rectangle. The RECT structure has the following form: 


typedef struct tagRECT { /* ro */ 
int left; ' 
int top; 
int right; 
int bottom; 
}: «RECT: 


This message does not return a value. 


Parameters 


Return Value 


Comments 


EM_SETRECT 

-EM_SETSEL 2x | 
EM_SETSEL 
wParam = (WPARAM) (UINT) fScrol1; /* flag for caret scrolling */ 


]Param = MAKELPARAM(ichStart, ichEnd); /* start and end positions */ 


An application sends an EM_SETSEL message to select a range of characters in 
an edit control. 


_SfScroll 


Value of wParam. When this parameter is zero, the caret is scrolled into view. 
When this parameter is 1, the caret is not scrolled into view. 


ichStart 
Value of the low-order word of /Param. Specifies the starting position. 


ichEnd 
Value of the high-order word of /Param. Specifies the ending position. 


The return value is nonzero if the message is sent to an edit control. 


If the ichStart parameter is O and the ichEnd parameter is —1, all the text in the edit 
control is selected. If ichStart is —1, any current selection is removed. The caret is 
placed at the end of the selection indicated by the greater of the two values ichEnd 
and ichStart. | : 


60 EM_SETTABSTOPS 


Example 


See Also 


This example sends an EM_SETSEL message to select the entire contents of an 
edit control. It then sends a WM_CUT message to copy the contents of the edit 
control to the clipboard and then to delete the contents of the edit control. 


SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_SETSEL, @, MAKELONG(@, -1)); 

SendDlgItemMessage(hdig, ID_MYEDITCONTROL, 
WM_CUT, @, OL); 


EM_GETSEL, EM_REPLACESEL 


EM _SETTABSTOPS 


Parameters 


Return Value 


Comments 


EM_SETTABSTOPS 
wParam = (WPARAM) cTabs; /* number of tab stops */ 
1Param = (LPARAM) (const int FAR*) IpTabs; /* tab-stop array. / 


An application sends an EM_SETTABSTOPS message to set the tab stops in a 
multiline edit control (MLE). When text is copied to an MLE, any tab character in 
the text causes space to be generated up to the next tab stop. 


This message is processed only by MLEs. 


cTabs 
Value of wParam. Specifies the number of tab stops contained in the /pTabs 
parameter. If this parameter is O, the /pTabs parameter is ignored and default 
tab stops are set at every 32 dialog box units. If this parameter is 1, tab stops are 
set at every n dialog box units, where 7 is the distance pointed to by the /pTabs 
parameter. If the cTabs parameter is greater than 1, /pTabs points to an array of 
tab stops. | 


IpTabs ee | 
Low and high-order words of /Param. Points to an array of unsigned integers 
specifying the tab stops, in dialog box units. If the cTabs parameter is 1, IpTabs 
points to an unsigned integer containing the distance between all tab stops, in | 
dialog units. : | 


The return value is nonzero if the tabs were set; otherwise, the return value is zero. 
The EM_SETTABSTOPS message does not automatically redraw the edit-control 


window. If the application is changing the tab stops for text already in the edit con- 
trol, it should call the InvalidateRect function to redraw the edit-control window. 


EM_SETWORDBREAKPROC _—s61 


Example This example sends an EM_SETTABSTOPS message to set tab stops at every 64 
dialog box units. It then calls InvalidateRect to redraw the edit-control window. 


WORD wlabSpacing = 64; 


SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_SETTABSTOPS, 1, (LPARAM) (int far*) &wTabSpacing); 
InvalidateRect(GetDlgItem(hdlg, ID_MYEDITCONTROL), 
NULL, TRUE); 


See Also  GetDialogBaseUnits 


EM_SETWORDBREAKPROC | BA 


EM_SETWORDBREAKPROC 
wParam = Q; /* not used, must be zero */ 
1Param = (LPARAM) (EDITWORDBREAKPROC) ewbprc; /* address of function */ 


An application sends the EM_SETWORDBREAKPROC message to an edit 
control to replace the default wordwrap function with an application-defined 
wordwrap function. 


Parameters ewbprc 
| Value of /Param. Specifies the procedure-instance address of the application- © 
defined wordwrap function. The MakeProcInstance function must be used to 
create the address. For more information, see the description of the Word- 
BreakProc callback function. 


\ 


Return Value This message does not return a value. 


Comments A wordwrap function scans a text buffer (which contains text to be sent to the dis- 
play), looking for the first word that does not fit on the current display line. The 
wordwrap function places this word at the beginning of the next display line. 


A wordwrap function defines the point at which Windows should break a line of 
text for multiline edit controls, usually at a space character that separates two 
words. Either a multiline or a single-line edit control might call this function when 
the user presses arrow keys in combination with the CTRL key to move the cursor 
to the next word or previous word. The default wordwrap function breaks a line of 
text at a space character. The application-defined function may define wordwrap 
to occur at a hyphen or a character other than the space character. 


See Also EM_GETWORDBREAKPROC, MakeProcInstance, WordBreakProc 


62 EM_UNDO 


EMUNDO : fr 


EM_UNDO 
wParam = Q@; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application sends an EM_UNDO message to undo the last edit-control 


operation. 
Parameters This message has no parameters. 
Return Value The return value is always nonzero for a single-line edit control. For a multiline 


edit control, the return value is nonzero if the undo operation is successful or zero 
if the wee operation fails. 


Comments An undo operation can also be undone. For example, you can restore deleted text 
with the first EM_UNDO message and remove the text again with a second 
EM_UNDO message as long as there is no intervening edit-control operation. 


Example This example undoes the last edit-control operation: 


SendD1gItemMessage(hd1g, ID_MYEDITCONTROL, EM_UNDO, 0, QL); 


See Also EM_CANUNDO 


LB ADDSTRING = ars 


LB_ADDSTRING 
wParam = @; /* not used, must be zero *f 
Param = (LPARAM) (LPCSTR) lpsz; /* address of aeerung to add */ 


An application sends an LB _ADDSTRING message to add a string to a list box. If 
the list box does not have the CBS_SORT style, the string is added to the end of 
the list. Otherwise, the string is inserted into the list and the list is sorted. 


Parameters — [psz- 
Value of lParam. Points to the null- tehininated string that is to be added. If the 
_ list box was created with an owner-drawn style but without the 
LBS_HASSTRINGS style, the value of the /psz parameter is Stored rather than 
the string it would otherwise point to. 


LB_DELETESTRING 63 


Return Value The return value is the zero-based index to the string in the list box. The return 
value is LB_ERR if an error occurs; the return value is LB_ ERRSPACE if insuffi- 
cient space is available to store the new string. 


Comments If an owner-drawn list box was created with the LBS_SORT style but not the 
LBS_HASSTRINGS style, the WM_COMPAREITEM message is sent one or 
more times to the owner of the list box so the new item can be properly placed in 

. the list box. 

Example | This example adds the string “my string” to a list box: . 
DWORD dwIindex; 
dwIndex = SendDigItemMessage(hdlg, ID_MYLISTBOX, 

LB_ADDSTRING, @, (LPARAM) ((LPCSTR) “my string")); 


See Also LB_DELETESTRING, LB_INSERTSTRIN G, WM_COMPAREITEM 


LB_DELETESTRING [2x] 


LB DELETESTRING 
wParam = (WPARAM) index; /* index of string to delete */ 
1Param OL; /* not used, must be zero * / 


An application sends an LB_DELETESTRING message to delete a string in a list 
box. 


Parameters — index | | 
Value of wParam. Specifies the zero-based index of the string to delete. 


Return Value | The return value is a count of the strings remaining in the list. The return value is 
| | LB_ERR if the index parameter specifies an index greater than the number of 
items in the list. | | 


Comments — _ If the list box was created with an owner-drawn style but without the 
| LBS_HASSTRINGS style, a WM_DELETEITEM message is sent to the owner of 
the list box so that the application can free any additional data associated with the 
item. : 


64 LB_DIR 


Example — This example deletes the first string in a list box: 


DWORD dwRemaining; 


dwRemaining = SendDilgItemMessage(hdlg, ID_MYLISTBOX, 
LB_DELETESTRING, @, @L); 


See Also | LB_ADDSTRING, WM_DELETEITEM | 


LB_DIR [2] 


LB_DIR 


wParam = (WPARAM) (UINT) uAttrs; /* file attributes + / 
TParam = (LPARAM) (LPCSTR) IpszFileSpec; /* filename string's address */ 


An application sends an LB_DIR message to add a list of filenames to a list box. 


Parameters uAttrs 
Value of wParam. Specifies the attributes of the files to be added to the list’ 
box. It can be any combination of the following values: 
Value Meaning 


0x0000 File can be read from or written to. 

0x0001 File can be read from but not written to. 

0x0002 File is hidden and does not appear in a directory listing. 

0x0004 File is a system file. 

0x0010 The name pointed to by the IpszFileSpec parameter specifies a directory. 

0x0020 File has been archived. | 

0x4000 All drives that match the name aPeeHACe by the IpszF oe parameter 
are included. 


-0x8000 Exclusive flag. If the exclusive flag is set, only files of the specified 
- type are listed. Otherwise, files of the specified type are listed in addi- 
tion to files that do not match the specified type. 


— lpszk ileSpec 
Value of /Param. Points to the null-terminated string that specifies the filename 
to add to the list. If the filename contains wildcards (for example, *.*), all files 
that match and have the attributes specified by the uAttrs parameter are added 
_ to the list. 


Return Value 


Example 


See Also 
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The return value is the zero-based index of the last filename added to the list. The 
return value is LB_ ERR if an error occurs; the return value is LB_ERRSPACE if 
insufficient space is available to store the new strings. 


This example adds the names of all available drives to a list box: 
DWORD dwIndexLastItem; 


dwindexLastItem = SendDigItemMessage(hdlg, ID_MYLISTBOX, LB_DIR, 
Q@x4000 | @x8000, (LPARAM) ((LPCSTR) "*")); 


DigDirList 


LB FINDSTRING os 


Parameters 


Return Value 


Comments 


LB_FINDSTRING 
wParam = (WPARAM) indexStart; /* item before start of search */ 
1Param (LPARAM) (LPCSTR) IpszFind; /* address of search string * / 


An application sends an LB_FINDSTRING message to find the first string ina list | 
box that contains the specified prefix. a 


indexStart 7 
Value of wParam. Specifies the zero-based index of the item before the first 
item to be searched. When the search reaches the bottom of the list box, it con- 
tinues from the top of the list box back to the item specified by the indexStart 
parameter. If indexStart is —1, the entire list box is searched from the beginning. 


lpszFind | 
Value of /Param. Points to the null-terminated string that contains the prefix to 
search for. The search is not case-sensitive, so this string can contain any combi- 
nation of uppercase and lowercase letters. 7 


The return value i is the index of the matching item, or itis LB _ERR if the search 
was unsuccessful. | 


If the list box was created with an owner-drawn style but without the 
LBS_HASSTRINGS style, the action taken by LB_FINDSTRING depends on 
whether the LBS_SORT style is used. If LBS_SORT is used, WM_COM- _ 


-PAREITEM messages are sent to the owner of the list box to determine which 
_ item matches the specified string. Otherwise, LB_FINDSTRING attempts to 
match the doubleword value against the value of [pszFind. | 
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Example This example searches for the string “my string” in a list box and copies it, if 
found, to the szBuf buffer: 


char szBuf[2@]; 
DWORD dwIindex; 


dwIndex = SendDlgItemMessage(hdlg, ID_MYLISTBOX, 
LB_FINDSTRING, @, (LPARAM) ((LPCSTR) "my string")); 
if (dwIndex != LB_ERR) 
SendDlgItemMessage(hdlg, ID_MYLISTBOX, 
LB_GETTEXT, (WPARAM) dwIndex, (LPARAM) ((LPCSTR) szBuf)); 


See Also LB_ADDSTRING, LB_FINDSTRINGEXACT, LB_INSERTSTRING 


LB_FINDSTRINGEXACT rar] 


LB_FINDSTRINGEXACT 
wParam = (WPARAM) indexStart; /* item before start of search */ 
1Param = (LPARAM) (LPCSTR) IlpszFind; /* address of search string a / 


An application sends an LB_FINDSTRINGEXACT message to find the first list 
box string that matches the string specified in the [pszF'ind parameter. 


Parameters | indexStart | 
| Value of wParam. Specifies the zero-based index of the item before the first 
item to be searched. When the search reaches the bottom of the list box, it con- 
tinues from the top of the list box back to the item specified by the indexStart 
parameter. If indexStart is —1, the entire list box is searched from the beginning. 


lpszFind 
Value of /Param. Points to the null-terminated string to search for. This string 
can contain a complete filename, including the extension. The search is not 
case-sensitive, so the string can contain any combination of uppercase and 
lowercase letters. 


Return Value The return value is the index of the matching item, or it is LB_ERR if the search 
was s unsuccessful. 
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Comments If the list box was created with an owner-drawn style but without the 
LBS_HASSTRINGS style, the action taken by LB_FINDSTRINGEXACT de- 
pends on whether the LBS_SORT style is used. If LBS_SORT 1s used, 
WM_COMPAREITEM messages are sent to the owner of the list box to deter- 
mine which item matches the specified string. Otherwise, LB_FINDSTRINGEX- 
ACT attempts to match the doubleword value against the value of IpszFind. | 


See Also LB_ADDSTRING, LB_FINDSTRING, LB_INSERTSTRING 


LB_GETCARETINDEX = Woe 


LB_ GETCARETINDEX , 
wParam Q; /* not used, must be zero */ 
1Param OL; /* not used, must be zero */ 


An application sends an LB _GETCARETINDEX message to determine the index 
—_ of the item that has the focus rectangle i in a multiple-selection list box. The item 
may or may not be selected. _ : 


Parameters _ This message has no parameters. 


-ReturnValue =—“The return value is the zero-based index of the item that has the focus rectangle in 
a list box. If the list box is a single-selection list box, the return value is | the index 


of the item that is selected, if any. 
é 


Example — This example sends an LB_GETCARETINDEX message to retrieve the index of 
the item that has the pe rectangle in the list box: : 


LRESULT IrIndex; 


~ IrIndex = SendD1gItemMessage(hdla, ID_ MYLISTBOX, 
~ LB_GETCARETINDEX, @, QL); 


~ See Also LB_SETCARETINDEX 
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LB _GETCOUNT ; "i 


LB_ GETCOUNT 
wParam Q; /* not used, must be zero */ 
1Param OL; /* not used, must be zero */ 


An application sends an LB_GETCOUNT message to retrieve the number of 
items in a list box. 


Parameters This message has no parameters. 

Return Value The return value is the number of items in the list box, or it is LB_ERR if an error 
OccuUIS. 

Comments The returned count is one greater than the index value of the last item (the index is 


~ zero-based). 
Example _ This example retrieves the number of items in a list box: 
- DWORD cListItems; 


cListItems = SendDlgItemMessage(hdlg, ID_MYLISTBOX, LB_GETCOUNT, 0, @); 
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LB_ GETCURSEL 
wParam = Q@; /* not used, must be zero */ 
1Param = OL; /* not used, must be zero */ 


An application sends an LB_GETCURSEL message to retrieve the index of the 
currently selected item, if any, in a single-selection list box. 


Parameters This message has no parameters. 


Return Value The return value is the zero-based index of the cuneany selected item. It is 
LB_ERR if no item is currently selected. 


Comments _ An application should use the LB_GETCARETINDEX to retrieve the index of the 
| item that has the focus rectangle in a multiple-selection list box. 


The LB_GETCURSEL message cannot be sent to a multiple-selection list box. 


Example 


See Also 
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This example retrieves the index of the currently selected string in a list box and 
then retrieves that string: 


char szBuf[2@]; 
DWORD dwindex; 


dwiIndex = SendDlgItemMessage(hdlg, ID_MYLISTBOX, LB_GETCURSEL, @, @); 
if (dwiIndex != LB_ERR) 
SendDilgItemMessage(hdilg, ID_MYLISTBOX, 
LB_GETTEXT, (WPARAM) dwIndex, (LPARAM) ((LPCSTR) szBuf)); 


LB_GETCARETINDEX 


LB_GETHORIZONTALEXTENT = 


- Parameters 


Return Value 


Comments 


Example 


See Also 


LB_GETHORIZONTALEXTENT 
wParam = Q; /* not used, must be zero */ 
Param = QL; /* not used, must be zero */ 


An application sends the LB_GETHORIZONTALEXTENT message to retrieve 
from a list box the width, in pixels, by which the list box can be scrolled horizon- 


tally if the list box has a horizontal scroll bar. 


This message has no parameters. | 
The return value is the scrollable width of the list box, in pixels. 


To respond to the LB_GETHORIZONTALEXTENT message, the list box must 


have been defined with the WS_HSCROLL style. 


This example gets the horizontal extent of a list box: 


SendDI gItemMessage(hDlg, ID_ MYLISTBOX, 
LB_ GETHORIZONTALEXTENT, @, OL); 


LB_SETHORIZONTALEXTENT 
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LB_GETITEMDATA _ a 


Parameters 


Return Value 


Example 


See Also 


LB_GETITEMDATA 
wParam (WPARAM) index; /* item index * / 
1]Param OL; /* not used, must be zero */ 


An application sends the LB_GETITEMDATA message to retrieve the 
application-supplied doubleword value associated with the specified item in a 
list box. (This is the value of the /Param parameter of an LB_SETITEMDATA 
message.) 


index 
Value of wParam. Specifies the zero-based index of the item. 


The return value is the doubleword value associated with the item, or it is 
LB_ERR if an error occurs. 


This example retrieves the value associated with an item in a list box. The value 1s 
the handle of a global memory object. 


HGLOBAL hLBData; 
LPSTR. IJpLBData; 
HWND hListBox; 
WPARAM nIndex; 


if ((hLBData = LOWORD(SendMessage(hListBox, LB _GETITEMDATA, 
nIndex, @L)))) { 
if ((1pLBData =-GlobalLock(hLBData))) { 
. /* Access or manipulate the data */ 
GlobalUnlock(hLBData); 


} 
} 


LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA 
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LB_GETITEMHEIGHT a 


Parameters 


Return Value 


Example 


~ See Also 


LB. GETITEMHEIGHT . | 
wParam = (WPARAM) index; /* item index * / 
7Param = QL; 3 /* not used, must be zero */ 


An application sends an LB_GETITEMHEIGHT message to determine the height 
of items in a list box. 


index 
Value of wParam. Specifies the zero-based index of the item in the list box. 
This parameter is used only if the list box has the 
LBS_OWNERDRAWVARIABLE style; otherwise, it should be set to zero. 


The return value ig the height, in pixels, of the items in the list box. The return 


value is the height of the item specified by the index parameter if the list box has 
the LBS_OWNERDRAWVARIABLE style. The return value is LB_ERR if an 
error occurs. 


This example sends LB _GET ITEMHEIGHT to retrieve the height of the items in | 
a list box: 


LRESULT eed: 


lIrHeight = Sendbig it emMec sage cdl d: ID_ MYLISTBOX, 
| ‘LBL GETITEMHEIGHT, @, OL); 


LB_SETITEMHEIGHT 
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LB_GETITEMRECT 7 
wParam = (WPARAM) index; /* jtem index a / 
1Param = (LPARAM) (RECT FAR*) Iprc; /* address of RECT structure */ 


An application sends an LB_GETITEMRECT message to retrieve the dimensions _ 
of the rectangle that bounds an item as it is currently displayed in the list uOx win- 


dow. 
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Parameters index | 
Value of wParam. Specifies the zero-based index of the item. 


lprc 
Value of /Param. Specifies a long pointer to a RECT structure that receives the 
client coordinates for the item in the list box. The RECT structure has the fol- 
lowing form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


Return Value The return value is LB_ERR if an error occurs. 
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LB_GETSEL 
wParam = (WPARAM) index; /* item index * / 
1Param = QL; /* not used, must be zero */ 


An application sends an LB_GETSEL message to retrieve the selection state of an 
item. | 


Parameters index 
Value of wParam. Specifies the zero-based index of the item. 


Return Value The return value is a positive number if an item is selected; otherwise, it is zero. 
The return value is LB_ERR if an error occurs. | 


See Also LB_SETSEL 
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LB_GETSELCOUNT 


LB_GETSELCOUNT : 
wParam = @; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero */ 


An application sends an LB_GETSELCOUNT message to retrieve the total num- 
ber of selected items in a multiple-selection list box. 


Parameters This message has no parameters. 


Return Value The return value is the count of selected items in a list box. The return value is 
LB_ERR if the list box is a single-selection list box. 


See Also | LB_SETSEL 


LB GETSELITEMS . 


LB _GETSELITEMS 
wParam = (WPARAM) cItems; /* maximum number of items */ 
1Param = (LPARAM) (int FAR*) IpItems; /* address of buffer - a / 


An application sends an LB_GETSELITEMS message to fill a buffer with an | 
array of integers that specify the item numbers of selected items in a multiple- 
selection list box. 


Parameters cltems 
Value of wParam. Specifies the maximum number of selected items whose 
item numbers are to be placed in the buffer. 


[pltems 
Value of /Param. Specifies a long pointer to a buffer large enough for the num- 
_ ber of integers specified by the c/tems parameter. 


~ Return Value The return value is the actual number of items placed in the buffer. The return 
value is LB_ERR if the list box is a single-selection list box. 


See Also -LB_GETSELCOUNT 
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LB.GETTEXT = sits ix 


LB_GETTEXT 
wParam = (WPARAM) index; _ /* item index * / 
1Param = (LPARAM) (LPCSTR) IpszBuffer; /* address of buffer */ 


An application sends an LB_GETTEXT message to retrieve a string from a list 
box. 


Parameters index : 
Value of wParam. Specifies the zero-based index of the string to retrieve. 
lpszBuffer | 
Value of lParam. Points to the buffer that receives the string. The buffer must 
have sufficient space for the string and a terminating null character. An 
LB_GETTEXTLEN message can be sent before the LB_GETTEXT message to 
retrieve the length, in bytes, of the string. 


Return Value The return value is the length of the string, in bytes, excluding the terminating null 
character. The return value is LB_ERR if the index parameter does not speenty a 
valid index. 

Comments If the list box was created with an owner-drawn style but without the 


-LBS_HASSTRINGS style, the buffer pointed to by the IpszBuffer parameter 
receives the doubleword value associated with the item. 


Example 7 This example retrieves the length of the first item in the list box, allocates suffi- 
cient memory for the string, and then sends an LB_GETTEXT message to retrieve 
the string: 


DWORD cbItemString; 
PSTR psz; 


cbItemString = SendDlgItemMessage(hdlg, ID_MYLISTBOX, 
LB_GETTEXTLEN, @, QL); 
if (cbItemString != LB_ERR) { 
psz = (PSTR) LocalAlloc(LMEM_FIXED, (WORD) cbItemString) ; 
sendDigItemMessage(hdlg, ID_MYLISTBOX, 
LB_GETTEXT, @, (LPARAM) ((LPCSTR) psz)); 


See Also LB_GETTEXTLEN 
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LB_GETTEXTLEN Pax] 


LB_GETTEXTLEN 
wParam (WPARAM) index; /* item index * / 
1Param = @L; /* not used, must be zero */ 


An application sends an LB_GETTEXTLEN message to retrieve the length of a 
string in a list box. 


Parameters index 
Value of wParam. Specifies the zero-based index of the string. 


Return Value The return value is the length of the string, in bytes, excluding the terminating null 
character. The return value is LB_ERR if the index parameter does not specify a 
valid index. 

| Example This example retrieves the length of the first item in the list box: 


-DWORD cbhItemString; 


cbItemString = SendDilgItemMessage(hdlg, ID_MYLISTBOX, 
LB_GETTEXTLEN, 0, QL); 


See Also LB_GETTEXT 


LB GETTOPINDEX i 


LB_GETTOPINDEX | 
wParam = @; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero */ 


An application sends an LB_GETTOPINDEX message to retrieve the index of the 
first visible item in a list box. Initially, the item with index 0 is at the top of the list 
box, but if the list box is scrolled, another item may be at the top. 

_ Parameters This message has no parameters. 


Return Value © The return value is the zero-based index of the first visible item in a list box. 


See Also | LB_SETTOPINDEX 
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LB_INSERTSTRING a 7 


Parameters 


Return Value 


Example 


See Also 


LB_INSERTSTRING . 
wParam = (WPARAM) index; |  /* item index * / 
1Param = (LPARAM) (LPCSTR) Ipsz; /* address of string to insert */ 


An application sends an LB_LINSERTSTRING message to insert a string into a list 
box. Unlike the LB_ADDSTRING message, the LB_INSERTSTRING message 
does not cause a list with the LBS_SORT style to be sorted. 


index . | | 
Value of wParam. Specifies the zero-based index of the position at which to in- 
sert the string. If this parameter is —1, the string is added to the end of the list. 


[psz 
Value of /Param. Points to the null-terminated string that is to be inserted. If 
the list was created with an owner-drawn style but without the 
LBS_HASSTRINGS style, the value of the /psz parameter is stored rather than 
the string it would otherwise point to. 


The return value is the index of the position at which the string was inserted. The 
return value is LB_ERR if an error occurs. The return value is LB_ERRSPACE if 
insufficient space is available to store the new string. 

This example inserts the string “my string” into the third position of the list box: 


SendDl gItemMessage(hdlg, ID_MYLISTBOX, 
LB_INSERTSTRING, 2, (LPARAM) ((LPCSTR) "my string")); 


LB_ADDSTRING 


LB_RESETCONTENT = its al 


Parameters 


Return Value 


LB_RESETCONTENT | a | 
wParam = @; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application s sends an LB_ RESETCONTENT message to remove all items from 


= alist box. 


This message has no parameters. 


This message does not return a value. 


Comments 


Example 


See Also 
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If the list box was created with an owner-drawn style but without the 
LBS_HASSTRINGS style, the owner of the list box receives a 
WM_DELETEITEM message for each item in the list box. 


This example removes all items from a list box: 


SendDlgItemMessage(hdlg, ID_MYLISTBOX, LB_RESETCONTENT, 0, QL); 


WM_DELETEITEM 


LB_SELECTSTRING [2.x | 


Parameters 


Return Value 


Comments 


LB_SELECTSTRING 
wParam (WPARAM) indexStart; /* item before start of search */ 
1]Param (LPARAM) (LPCSTR) lpszFind; /* address of search string * / 


An application sends an LB_SELECTSTRING message to search the list box for 
an item that matches the specified string, and if a matching item is found, to select © 
the item. 


indexStart 
Value of wParam. Specifies the zero-based index of the item before the first 
item to be searched. When the search reaches the bottom of the list box, it con- 
tinues from the top of the list box back to the item specified by the indexStart 
parameter. If indexStart is —1, the entire list box is searched from the beginning. 


[pszF ind 
Value of /Param. Points to the null-terminated string that contains the prefix to 
search for. The search is not case-sensitive, so this string can contain any combi- 
nation of uppercase and lowercase letters. 


The return value is the index of the selected item if the search was successful. The 
return value is LB_ERR if the search was unsuccessful and the current selection is 


‘not changed. 


The list box is scrolled, if necessary, to bring the selected item into view. 


An item is selected only if its initial characters (from the starting point) match the 
characters in the string specified by the /pszF ind parameter. 
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If the list box was created with an owner-drawn style but without the LBS_HAS- 
STRINGS style, the action taken by LB_SELECTSTRING depends on whether 
the LBS_SORT style is used. If LBS_SORT is used, WM_COMPAREITEM 
messages are sent to the owner of the list box to determine which item matches 
the specified string. Otherwise, LB_SELECTSTRING re to match the © 
doubleword value against the value of [pszFind. 


Example This example searches the entire list box for an item that matches the string “my 
string”’ and, if the item is found, selects it: 


DWORD dwIndexFoundString; 


dwIndexFoundString = SendDlgItemMessage(hdlg, ID_MYLISTBOX, 
LB_SELECTSTRING, -1, (LPARAM) ((LPCSTR) "my string")); 


See Also — | LB_ADDSTRING, LB_FINDSTRING, LB_INSERTSTRING 


LB_SELITEMRANGE 


LB_- SELITEMRANGE 
wParam = (WPARAM) (BOOL) fSelect; /* selection flag * / 
1Param = MAKELPARAM(wFirst, wLlast); /* first and last items */ 


An application sends an LB_SELITEMRANGE message to select one or more 
consecutive items in a multiple-selection list box. 


Parameters fSelect 
Value of wParam. Specifies how to set the selection. If the fSe/ect parameter is 
nonzero, the string is selected and highlighted; if fSe/ect is zero, the highlight is 
removed and the string is no longer selected. 


WFirst 
Value of the low- order word of /Param. Specifies the zero-based index of the 
first item to set. 


wLast 
Value of the high-order word of /Param. Specifies the zero-based index of the 
last item to set. 
Return Value — The return value is LB_ ERR if an error occurs. 


Comments _ This message should be used only with multiple-selection list boxes. 
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LB_SETCARETINDEX 


Parameters | 


Return Value 


Example 


See Also 


LB_SETCARETINDEX 
wParam = (WPARAM) index; /* item index © * / 
1Param = MAKELPARAM(fScroll, 8); /* flag for scrolling item */ 


An application sends an LB _SETCARETINDEX message to set the focus rect- 
angle to the item at the specified index in a multiple-selection list box. If the item 
is not visible, it is scrolled into view. 


index 
Value of wParam. Specifies the zero-based index of the item to receive the 
focus rectangle in the list box. 


jScroll | | 
Value of /Param. If this value is zero, the item is scrolled until it is fully visible. 
If this value is nonzero, the item is scrolled until it is at least partially visible. 


The return value is LB_ERR if an error occurs. 


This example sends an LB_LSETCARETINDEX message to set the focus rectangle 
to an item in a list box: 


WPARAM wiIndex; 
wiIndex = Q; /* set index to first item */ 


SendDigItemMessage(hdlg, ID_MYLISTBOX, LB_SETCARETINDEX, 
wiIndex, @L); 


LB_GETCARETINDEX 


LB_SETCOLUMNWIDTH 


LB_SETCOLUMNWIDTH | | 
wParam = (WPARAM) cxColumn; /* column width * / 
1Param = OL; /* not used, must be zero */ 


An application sends an LB_SETCOLUMNWIDTH message to a multiple- _ 
column list box (created with the LBS_MULTICOLUMN style) to set the width, 
in pixels, of all columns in the list box. 
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Parameters 


Return Value 


Example 


cxColumn * 
Value of wParam. Specifies the width, in pixels, of all columns. 


This message does not return a value. 


This example sets the width of the columns in a multiple-column list box: 
WPARAM wColWidth; 
wColWidth = 100; /* set column width to 100 pixels */ 


SendDigItemMessage(hDlg, ID_MYLISTBOX, LB_SETCOLUMNWIDTH, 
wColWidth, @L); 


LB SETCURSEL SS era 


Parameters 


Return Value 
- Comments 


See Also 


LB. SETCURSEL 
wParam (WPARAM) index; /* item index * / 
1Param OL; /* not used, must be zero */ 


An application sends an LB_LSETCURSEL message to select a string and scroll it 
into view, if necessary. When the new string is selected, the list box removes the 
highlight from the previously selected string. 


index | 
Value of wParam. Specifies the zero-based index of the string that is selected. 
If the index parameter is —1, the list box is set to have no selection. 


The return value is LB_ERR if an error occurs. The return value will be LB_LERR 
even though no error has occurred if the index parameter is —1. 


This message should be used only with single-selection list boxes. It cannot be 
used to set or remove a selection in a multiple-selection list box. 


_~LB_GETCURSEL 
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LB_SETHORIZONTALEXTENT = 


LB_SETHORIZONTALEXTENT 
wParam = (WPARAM) cxExtent; /* horizontal scroll width */ 
1Param OL; /* not used, must be zero ¥*/ 


An application sends the LB_SETHORIZONTALEXTENT message to set the 
width, in pixels, by which a list box can be scrolled horizontally. If the size of the 
list box is smaller than this value, the horizontal scroll bar horizontally scrolls 
items in the list box. If the size of the list box is equal to or greater than this value, 
the horizontal scroll bar is hidden. 


Parameters cxExtent 
Soe Value of wParam. Specifies the number of pixels by which the list box can 1 be 
scrolled. 
Return Value This message does not return a value. | 
Comments To respond to the LB_SETHORIZONTALEXTENT message, the list box must 


have been defined with the WS_HSCROLL style. 


By default, the horizontal extent of a list box is zero. Windows does not display 
the scroll bar unless the horizontal extent is set to a value greater than the width, in 
pixels, of the client area of the list box. 


Example This example sets the horizontal extent of a list box based on the width of the 

| | string about to be added to the list box. The horizontal extent is set if the string is 
wider than the widest string in the list box and is wider than the client area of the 
list box. 


DWORD dwStringExt; 
HDC hdcLB; 
~ PSTR pszString; 
TEXTMETRIC tm; 
WORD wLongest; 
WORD wLBWidth; 


dwStringExt = GetTextExtent(hdcLB, (LPSTR) pszString, 
strlen(pszString)) + tm.tmAveCharWidth; 
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if ((LOWORD(dwStringExt) > wLongest) && 
(LOWORD(dwStringExt) > wLBWidth)) { 
SendDlgItemMessage(hDlg, ID_MYLISTBOX, LB _SETHORIZONTALEXTENT, 
LOWORD(dwStringExt), @L); 
wLongest = LOWORD(dwStringExt) ; 
} | | 


SendDlgItemMessage(hDlg, ID_MYLISTBOX, LB_ADDSTRING, @, 
(LPARAM) ((LPCSTR) pszString)); 


See Also ‘LB_GETHORIZONTALEXTENT 


LB_SETITEMDATA ) 


LB_SETITEMDATA 
wParam = (WPARAM) index; /* item index * / 
1Param = (LPARAM) dwData; /* value to associate with item */ 


An application sends the LB_SETITEMDATA message to set a doubleword value 
associated with the specified item in a list box. 


Parameters index 
Value of wParam. Specifies the zero- pases nex of the item. 


dwData 
Value of /Param. Specifies the value to be associated with the item. 


Return Value The return value is LB_ERR if an error occurs. 
Example This example associates a handle of a 64-byte memory object with each item in a 
list box: 


HGLOBAL hLBData; 
LPSTR = 1pLBData; 
HWND hListBox; 
WPARAM nIndex; 


case WM_INITDIALOG: 
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if ((hLBData = GlobalAlloc(GMEM_MOVEABLE, 64))) { 
if ((1pLBData = GlobalLock(hLBData))) { 


. /* Store the data in the memory object. */ 


GlobalUnlock(hLBData) ; 
} 
} | | | | 
SendMessage(hListBox, LB_SETITEMDATA, nIndex, 
MAKELONG(hHLBData, @)); 


See Also | LB_ADDSTRING, LB_GETITEMDATA, LB_INSERTSTRING 


LB SETITEMHEIGHT =—s_—«#w ra] 


LB_SETITEMHEIGHT 
wParam = (WPARAM) index; /* item index */ 
}Param = MAKELPARAM(cyItem, 9); /* item height */ 


An application sends an LB_SETITEMHEIGHT message to set the height of 
items in a list box. If the list box has the LBS_OWNERDRAWVARIABLE style, 
this message sets the height of the item specified by the wParam parameter. Other- 
wise, this message sets the height of all items in the list box. 


Parameters index | 

Value of wParam. Specifies the zero-based index of the item 1 in n the list box. 
This parameter is used only if the list box has the 
LBS_OWNERDRAWVARIABLE style; otherwise, it should be set to zero. 


On 
- Value of the low- order word of lParam. Pees the height, in aiele of the - 
item. 
ReturnValue -—‘ The return value is LB_ERR if the index or height iS invalid. . 
Example This example sends an LB _SETITEMHEIGHT message to set the Reign of the < 


items in a list box: 
LPARAM IpmHeight; 


SendD1gItemMessage(hdlg, 1D_ MYLISTBOX, -LB_SETITENHEIGHT, 
cee @, Tome Tone); | | pees ae 


~SeeAlso - LB_GETITEMHEIGHT 
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LB SETSEL x 


LB_SETSEL 
wParam = (WPARAM) (BOOL) fSelect; /* selection flag */ 
1Param = MAKELPARAM( index, @); /* item index * / 


An application sends an LB_SETSEL message to select a string in a multiple- 
selection list box. | 


Parameters fSelect | 7 

Value of wParam. Specifies how to set the selection. If the fSelect parameter is 
TRUE, the string is selected and highlighted; if {Select is FALSE, the highlight 
is removed and the string is no longer selected. 

index | 
Value of the low-order word of /Param. Specifies the zero-based index of the 
string to set. If the index parameter is —1, the selection is added to or removed 
from all strings, depending on the value of fSelect. 


Return Value The return value is LB_ERR if an error occurs. 
Comments This message should be used only with multiple-selection list boxes. 
SeeAlso LB_GETSEL 


LB_SETTABSTOPS 


LB_SETTABSTOPS 
wParam (WPARAM) cTabs; /* number of tab stops * / 
1Param = (LPARAM) (int FAR*) IpTabs; /* address of tab-stop array */ 


An application sends an LB_SETTABSTOPS message to set the tab-stop posi- 
tions in a list box. 


Parameters — cTabs | 
| Value of wParam. Specifies the number of tab stops in the list box. 


lpTabs 
Value of /Param. Points to the first member of an array of integers containing 
the tab stops, in dialog box units. The tab stops must be sorted in increasing 
order; back tabs are not allowed. 


Return Value 


Comments 


~ LB_SETTOPINDEX 


Parameters 


Return Value 


Comments | 


LB_SETTOPINDEX 9&5 


The return value is nonzero if all the tabs were set; otherwise, the return value is 
zero. | 


To respond to the LB_SETTABSTOPS message, the list box must have been 
created with the LBS_USETABSTOPS style. 


If the cTabs parameter is zero and the /pTabs parameter is NULL, the default tab 
stop is two dialog box units. : 


If cTabs is 1, the edit control will have tab stops separated by the distance 
specified by [pTabs. 


If lpTabs points to more than a single value, a tab stop will be set for each value in 


lpTabs, up to the number specified by cTabs. 


A dialog box unit is a horizontal or vertical distance. One horizontal dialog box — 
unit is equal to one-fourth of the current dialog box base width unit. The dialog 
box base units are computed based on the height and width of the current system _ 
font. The GetDialogBaseUnits function returns the current dialog box base units, 
in pixels. | 


LB_SETTOPINDEX ae 
wParam = (WPARAM) index; | /* item index , * / 
(Param: QL; /* not used, must be zero */ 


An application sends an LB .SEEIOPIN DEX message to ensure that a navticulit 


| item in a list box is visible. 


index | 
Value of wParam. Specifies the zero-based index of the item in the list box. 


The return value is LB_ERR if an error SceUrs: 


The system scrolls the list box so that either the specified item appears at the isp” 


_ of the list box or the maximum scroll range has been reached. 
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Example _ This example searches for an item in a list box that matches the string “my string” 
| and, if a match is found, ensures that the item is visible: 


int iIndex; 
iIndex = (int) SendMessage(hMyListbox, LB_FINDSTRING, -1, 
(LPARAM) (LPCSTR) “my string"); 


if (iIndex != LB_ERR) . 
SendMessage(hMyListbox, LB_SETTOPINDEX, (WPARAM) iIndex, QL); 


See Also LB_GETTOPINDEX 


STM_GETICON aa 


STM_GETICON 
wParam = Q; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application sends an STM_GETICON message to retrieve the handle of the 
icon associated with an icon resource. 


Parameters This message has no parameters. 


Return Value The return value is the icon handle if the operation is successful, or it is zero if the 
icon has no associated icon resource or if an error occurred. 


Example This example gets the handle of the icon associated with an icon resource: 


~ HICON hIcon; 


hIcon = (HICON) SendDIigItemMessage(hdig, IDD_ICON, | 
STM_GETICON, 0, QL); 


See Also STM_SETICON 
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STM_SETICON = ee 


STM_SETICON | 
wParam = (WPARAM) (HICON) hicon; /* handle of the icon fe 
1Param = @L; /* not used, must be zero */ 


An application sends an STM_SETICON message to associate an icon with an 
icon resource. 


Parameters — hicon 
Value of wParam. Identifies the icon to associate with the icon resource. 


Return Value The return value i is the handle of the icon that was previously associated with the 
: icon resource, or it is zero if an error occurred. 


Example This example associates the eee ee question-mark icon with an icon re- | 
source: | 


HICON hIcon, hOldIcon; 


hIcon = LoadIcon((HANDLE) NULL, IDI_QUESTION); 
hOldIcon = (HICON) SendDlgItemMessage(hdig, IDD_ICON, 
STM_SETICON, hIcon, QL); 


SeeAlso STM GETICON 


WM_ ACTIVATE a] 


WM_ACTIVATE 


fActive = wParam; /* activation flag */ 
fMinimized = (BOOL) HIWORD(1Param); /* minimized flag */ 


hwnd = (HWND) LOWORD(1Param) ; _ /* window handle */ 


The WM_ACTIVATE message is sent when a window is being activated or 
deactivated. This message is sent first to the window procedure of the main win- 
dow being deactivated and then to the window procedure of the main window 
being activated. : 


Parameters factive oe 
ot Value of wParam. Specifies whether the rindow: iS being activated or deacti- © 
vated. It can be one eof the following values: bare 
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Value | Description 
WA_INACTIVE The window is being deactivated. 
WA_ACTIVE The window is being activated through some e method 


other than a mouse click (for example, by use of the key- 
board interface to select the window). 


WA_CLICKACTIVE The window is being activated by a mouse click. 


fMinimized ) 
Value of the high-order word of /Param. Specifies the minimized state of the 
window being activated or deactivated. A nonzero value indicates the window 
is minimized. 

hwnd 
Value of the low-order word of /Param. Identifies the window being activated 
or deactivated. This handle can be NULL. 


Return Value An application should return zero if it processes this message. 


Comments If the window is activated with a mouse click, it also receives a 
WM_MOUSEACTIVATE message. 


Example _ This example sets the input focus while processing the WM_ACTIVATE message: 
case WM_ACTIVATE: 


if (wParam && !HIWORD(1Param) ) 
SetFocus (hwnd) ; 
break; 


See Also WM_MOUSEACTIVATE, WM_NCACTIVATE 


WM_ACTIVATEAPP | [2x] 


WM_ACTIVATEAPP 
fActive = (BOOL) wParam; /* the activation/deactivation flag */ 
htask = (HTASK) LOWORD(1Param); /* task handle * / 


The WM_ACTIVATEAPP message is sent when a window is about to be acti- 
vated and that window belongs to a different task than the active window. The 
message is sent to all top-level windows of the task being activated et to all top- 
level windows of the task being deactivated. 
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Parameters fActive 
| Value of wParam. Specifies whether the window is being activated or deacti- 
vated. A nonzero value means the window is being activated. A zero value 
means the window is being deactivated. 


htask 
Value of the low-order word of /Param. Specifies a task handle. If the fActive 
parameter is nonzero, the handle identifies the task that owns the window being 
deactivated. If fActive is zero, the handle identifies the task that owns the win- 
dow being activated. 


Return Value _ An application should return zero if it processes this message. 


See Also WM_ACTIVATE 


WM_ASKCBFORMATNAME let ae 


WM_ASKCBFORMATNAME | 
wParam = (WPARAM) cbMax; 7 /* maximum bytes to copy */ 
1Param = (LPARAM) lpszFormatName; /* address of format name */ 


A clipboard viewer application sends a WM_ASKCBFORMATNAME message 
to the clipboard owner when the clipboard contains the data handle of the 
CF_OWNERDISPLAY format (that is, when the clipboard owner should display 
the clipboard contents). 


Parameters chMax | 
Value of wParam. Specifies the maximum number of bytes to copy. 


lpszFormatName , 
Value of /Param. Points to the buffer where the copy of the format name is to 
be stored. | 


Return Value An application should return zero if it processes this message. 


Comments The clipboard owner should copy the name of the CF_OWNERDISPLAY format 
_ into the specified buffer, not exceeding the maximum number of bytes. 


See Also WM_PAINTCLIPBOARD 
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WM_CANCELMODE . ie 


The WM_CANCELMODE message is sent to inform a window to cancel any in- 
ternal mode. This message is sent to the focus window when a dialog box or mes- 
sage box 1s displayed, giving the focus window the opportunity to. cancel modes 
such as mouse capture. 


Parameters This message has no parameters. 
Return Value An application should return zero if it processes this message. 
Comments The DefWindowProc function processes this message by calling the Release- 


Capture function. DefWindowProc does not cancel any other modes. 


See Also | DefWindowProc, ReleaseCapture 


wel CHANGECBCHAIN [Bx] 


WM_ CHANGECBCHAIN 
hwndRemoved = (HWND) wParam; /* handle of removed window */ 
hwndNext = (HWND) LOWORD(1Param) ; /* handle of next window * / 


The WM_CHANGECBCHAIN message notifies the first window in the epee 
viewer chain that a window is being removed from the chain. 


Parameters hwndRemoved 
| Value of wParam. Identifies the window that is being removed from the 
clipboard-viewer chain. 


hwndNext 
Value of the low-order word of /Param. Identifies the window that follows the 
window being removed from the clipboard-viewer chain. 


Return Value — An application should return zero if it processes this message. 


Comments 


See Also 


WM_CHAR 


Parameters 
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Each window that receives the WM_CHANGECBCHAIN message should call 
the SendMessage function to pass the message on to the next window in the — 
clipboard-viewer chain. If the window being removed is the next window in the 
chain, the window specified by the hwndNext parameter becomes the next window 
and clipboard messages are passed on to it. 


ChangeClipboardChain, SendMessage _ 


WM_CHAR | 
nVKey = wParam; | /* virtual-key code */ 
dwkeyData = (DWORD) ]Param; /* key data * / 


The WM_CHAR message is sent when a WM_KEYUP message and a 
WM_KEYDOWN message are translated. The WM_CHAR message contains the 
value of the key being pressed or released. 


nVKey 
Value of wParam. Specifies tl the virtual- -key code value of the key. 


dwKeyData 
Value of /Param. Specifies the repeat count, scan code, extended key, context 
code, previous Key state, and key-transition state, as shown in the following 
table: 


Bit Description 
0-15 Specifies the repeat count. The value is the number of times the keystroke 
| is repeated as a result of the user holding down the key. 


16-23 Specifies the scan code. The value.depends on the original equipment 
manufacturer (OEM). 


24 Specifies whether the key is an extended key, such as a function key ora 
key on the numeric keypad. The value is 1 if itis an extended key; other- 
| wise, it is 0. 
25-26 Not used. 


27-28 _ Used internally by Windows. 


29 _ Specifies the context code. The value is 1 if the ALT key i is held down 
while the key is pressed; otherwise, the value is 0. 
30 Specifies the previous key state. The value is 1 if the key is down before 


the message is sent, or it is O if the key is up. 


31 Specifies the key-transition state. The value is 1 if the key is being re- 
leased, or it is 0 if the key is being pressed. 
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Return Value An application should return zero if it processes this message. 


Comments Because there is not necessarily a one-to-one correspondence between keys 
pressed and character messages generated, the information in the high-order word 
of the dwKeyData parameter is usually not useful to applications. The information 
in the high-order word applies only to the most recent WM_KEYUP or - | 
WM_KEYDOWN message that precedes the posting of the character message. © 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
key and the right CTRL key on the main section of the keyboard; the INS, DEL, 
HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the 
numeric keypad; and the division (/) and ENTER keys on the numeric keypad. Some 
other keyboards may support the extended-key bit in the dwKeyData parameter. 


See Also WM_KEYDOWN, WM_KEYUP 


WM_CHARTOITEM : 


WM_CHARTOITEM 


nKey = wParam; /* key value * / 
hwndListBox = (HWND) LOWORD(1Param); /* list box handle */ 
iCaretPos = HIWORD(1Param) ; /* caret position */ 


The WM_CHARTOITEM message is sent by a list box with the | 
LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_CHAR 
message. 


Parameters - nKey 
| . Value of wParam. Specifies the value of the Key the user pressed. 


hwndListBox 
Value of the low-order word of /Param. Identifies the list box. 


| iCaretPos 
Value of the high-order word of lParam. Specifies the current caret position. 


Return Value The return value specifies the action that the application Beronned in response to 
| the message. A return value of —2 indicates that the application handled all aspects 
of selecting the item and requires no further action by the list box. A return value 
of —1 indicates that the list box should perform the default action in response to 
the keystroke. A return value of 0 or greater specifies the zero-based index of an 
item in the list box and indicates that the list box should perform the default action 
— for the keystroke on the given item. 


WM_CHOOSEFONT_GETLOGFONT 93 


Comments Only Syne list boxes that do not have the LBS _HASSTRINGS style can 
receive this message. 


See Also -WM_CHAR, WM_VKEYTOITEM 


WM_CHILDACTIVATE — - 


WM_CHILDACTIVATE 


The WM_CHILDACTIVATE message is sent to a multiple document interface 
(MDI) child window when the user clicks the window’s title bar or when the win- 
dow is activated, moved, or sized. 


Parameters This message has no parameters. 
Return Value An application should return zero if it processes this message. 
See Also MoveWindow, SetWindowPos 


WM_CHOOSEFONT_ GETLOGFONT oe 


WM_CHOOSEFONT_GETLOGFONT 
wParam = Q@; /* not used, must be zero * / 
Tplf = (LPLOGFONT) 1Param; /* address of a LOGFONT structure */ 


An application sends a WM_CHOOSEFONT_GETLOGFONT message to the 
Font dialog box created by the ChooseF ont function to retrieve the current 
LOGFONT structure. 


Parameters Iplf 
Points to a LOGFONT structure that receives information about the current 


logical font. 


- Return Value This message does not return a value. 
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Comments An application uses this message to retrieve the LOGFONT structure while the 
Font dialog box is open. When the user closes the dialog box, the ChooseF ont 
function receives information about the LOGFONT structure. 


See Also WM_GETFONT 


WM_CLEAR a og 


WM_CLEAR 
wParam = Q; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero */ 


An application sends a WM_CLEAR message to an edit control or combo box to 
delete (clear) the current selection, if any, in the edit control. 


Parameters This message has no parameters. 
Return Value The return value is nonzero if this message is sent to an edit control or a combo 
: box. 
Comments | The deletion performed by the WM_CLEAR message can be undone by sending 


the edit control an EM_UNDO message. 


To delete the current selection and place the deleted contents into the clipboard, 
use the WM_CUT message. | | 


Example This example sends an EM_SETSEL message to select the entire contents of an | 
| edit control. It then sends a WM_CLEAR message to delete the contents of the 
edit control. | | 


SendDigItemMessage(hdlg, ID _MYEDITCONTROL, 
EM_SETSEL, @, MAKELONG(Q, -1)); 

sendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
WM_CLEAR, @, OL); 


SeeAlso = _EM_UNDO,WM_COPY,WM_CUT,WM_PASTE | 


WM_ CLOSE 


Parameters 
~ Return Value 


Example 


See Also 
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[2x] 


WM_CLOSE | 
wParam = @; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


The WM_CLOSE message is sent as a signal that a window or an application 
should terminate. An application can prompt the user for confirmation prior to 
destroying the window by processing the WM_CLOSE message and calling the 
Destroy Window function only if the user confirms the choice. 


This message has no parameters. 


An application should return zero if it processes this message. 


This example processes a WM_CLOSE message and requests confirmation from 
the user before terminating the application: 


case WM_CLOSE: . , 
if (MessageBox(hwnd, "Are you sure you want to exit?", "MyApp", 
MB_ICONQUESTION | MB_OKCANCEL) == IDOK) 
DestroyWindow(hwnd) ; 
return @L; 


Destroy Window, PostQuitMessage WM_DESTROY, WM_QUIT 


-WM_COMMAND oo ia 


WM_ COMMAND ) 

idItem = wParam; /* control or menu item identifier _ * / 
hwndCtl = (HWND) LOWORD(1Param); /* handle of control * / 
wNotifyCode = HIWORD(1Param); /* notification message a / 


The WM_COMMAND message 1s sent to a window when the user selects an item > 
from a menu, when a control sends a notification message to its parent window, or 


when an accelerator keystroke is translated. 
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Parameters 


Return Value 


Comments 


Example 


See Also 


‘idItem 
Value of wParam. Specifies the identifier of the menu item or control. 


hwndCtl 
Value of the low-order word of /Param. Identifies the control sending the mes- 
sage if the message is from a control. Otherwise, this parameter is zero. 


wNotifyCode 
Value of the high-order word of /Param. Specifies the notification message if 
the message is from a control. If the message is from an accelerator, this 
parameter is 1. If the message is from a menu, this parameter is 0. 


An application should return zero if it processes this message. 


Accelerator Keystrokes that are defined to select items from the System menu 
(sometimes referred to as the Control menu) are translated into 
WM_SYSCOMMAND messages. 


If an accelerator keystroke that corresponds to a menu item occurs when the win- 
dow that owns the menu is minimized, no WM_COMMAND message is sent. 
However, if an accelerator keystroke occurs that does not match any of the items 
on the window’s menu or on the System menu, a WM_COMMAND message is 
sent even if the window is minimized. 


This example creates an Options dialog box in pak toa WM_COMMAND 
message sent as a result of a menu selection: - 


FARPROC IpProc; 


case WM_COMMAND: 
Switch (wParam) { 
case IDM_OPTIONS: = 
IpProc = MakeProcInstance(OptionsProc, hInstance) ; 
DialogBox(hInstance, "OptionsBox", hwnd, IpProc); 
FreeProcInstance(1pProc); | 
break; 


. /* Process other menu commands. */ 


ae 
break; 


WM_SYSCOMMAND 
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WM_COMMNOTIFY e828 Bg 


Parameters 


Return Value 


Comments 


See Also | 


WM_COMMNOTIFY 
idDevice = wParam; /* communication-device ID */ 
nNotifyStatus = LOWORD(1Param); /* notification-status flag */ 


The WM _COMMNOTIFY message is posted by a communication device driver 
whenever a COM port event occurs. The message indicates the status ofa a win- 
dow’s input or output queue. 


idDevice 
Value of wParam. Specifies the identifier of the communication device that i 1S 
posting the notification message. 


nNotifyStatus 
Value of the low-order word of lParam. Specifies the notification status in the 
low-order word. The notification status may be one or more - of the following 
flags: | | : 


Value | Meaning 


CN_EVENT Indicates that an event has occurred that was enabled in the 
i : event word of the communication device. This event was 
enabled by a call to the SetCommEventMask function. The 
- application should call the GetCommEventMask function to 
determine which event occurred and to clear the event. 


CN_RECEIVE | Indicates that at least cbWriteNotify bytes are in the input. 
queue. The cbWriteNotify parameter is a parameter of the 
EnableCommNotification function. 


CN_TRANSMIT Indicates that fewer than chOutQueue bytes are in the output 
queue waiting to be transmitted. The cbOutQueue parameter _ 
is a parameter of the EnableCommNotification function. 


An application should return zero if it processes this message. 


This message is sent only when the event word changes for the communication 


device. The application that sends WM_COMMNOTIFY must clear each event to 


be sure Of receiving future notifications. 


: EnableCommNotification 
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WM_ COMPACTING ae 


WM_COMPACTING 
wCompactRatio = wParam; /* compacting ratio */ 


The WM_COMPACTING message is sent to all top-level windows when Win- 
dows detects that more than 12.5 percent of system time over a 30- to 60-second 
interval is being spent compacting memory. This indicates that system memory is 
low. 


Parameters wCompactRatio 
Value of wParam. Specifies the ratio of central processing unit (CPU) time cur- 
rently spent by Windows compacting memory to CPU time currently spent by 
Windows performing other operations. For example, 0x8000 represents 50 per- 
cent of CPU time spent compacting memory. 


Return Value An application should return zero if it processes this message. 


Comments When an application receives this message, it should free as much memory as 
possible, taking into account the current level of activity of the application and the 
total number of applications running with Windows. The application can call the 
GetNumTasks function to determine how many applications are running. 


See Also | GetNumTasks 


WM_COMPAREITEM 


WM_COMPAREITEM | 
idCtl = wParam; /* control identifier */ 
Ipcis = (const COMPAREITEMSTRUCT FAR*) 1Param; /* structure * / 


The WM_COMPAREITEM message determines the relative position of a new 
item in the sorted list of an owner-drawn combo box or list box. Whenever the ap- 
plication adds a new item, Windows sends this message to the owner of a combo 
box or list box created with the CBS_SORT or LBS_SORT style. | 


Parameters 


| Return Value 


Comments 


See Also 


WM_COMPAREITEM 


idCtl 7 
Value of wParam. Specifies the identifier of the control that sent the 
WM_COMPAREITEM message. 


lpcis 
Value of [Param. Points to a COMPAREITEMSTRUCT data structure that | 
contains the identifiers and application-supplied data for two items in the 


o aes 


~ combo box or list box. The COMPAREITEMSTRUCT structure has the fol- 


lowing form: 


typedef struct tagCOMPAREITEMSTRUCT { /* cis */ 
UINT CtlType; 
UINT CtlID; 
HWND hwndIten; 
UINT itemID1; 
DWORD itemDatal; 
UINT itemID2; 
DWORD itemData2; 
} a a 


The return value indicates the relative position of the two items. It may be any of 
the following values: 


Value Meaning 

—] Item 1 precedes item 2 in the sorted order. | 
0 Item 1 and item 2 are equivalent in the sorted order. 
1 Item 1 follows item 2 in the sorted order. 


When the owner of an owner-drawn combo box or list box receives this _ 
message, the owner returns a value indicating which of the items specified in the 


Windows sends this message several times until it determines the exact position 
for the new item. 


COMPAREITEMSTRUCT 


~ COMPAREITEMSTRUCT structure should appear before the other. Typically, | 
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-WM_COPY — ge ax 


WM_COPY 
wParam = Q; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application sends a WM_COPY message to an edit control or combo box to 
copy the current selection to the clipboard in CF_TEXT format. 


Parameters This message has no parameters. 
Return Value — The return value is nonzero if this message is sent to an edit control or a combo 
box. | 
Example This example sends an EM_SETSEL message to select the entire contents of an 
edit control. It then sends a WM_COPY message to copy the contents of the edit 
control to the clipboard. 


SendDIl gItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_SETSEL, @, MAKELONG(@, -1)); 

SendDigItemMessage(hdlg, ID_MYEDITCONTROL, 
WM_COPY, @, OL); © 


See Also WM_CLEAR, WM_CUT, WM_PASTE 


WM_CREATE : es 


WM_CREATE | | 
Tpcs = (CREATESTRUCT FAR*) 1Param; /* structure address * / 


The WM_CREATE message is sent when an application requests that a window 
be created by calling the CreateWindowEx or CreateWindow function. The win- 
dow procedure for the new window receives this message after the window is 
created but before the window becomes visible. The message is sent to the win- 
dow before the CreateWindowEx or CreateWindow function returns. 


Parameters —— Ipes | ; | 
| | Value of lParam. Points to a CREATESTRUCT data structure containing in- 
formation about the window being created. The members of the CREATE- 
STRUCT structure are identical to the parameters of the CreateWindowEx 
function. : 


Return Value 


See Also — 


WM_CTLCOLOR 101 


The CREATESTRUCT structure has the following form: 


typedef struct tagCREATESTRUCT {  /* cs */_ 
void FAR* IpCreateParams; 
HINSTANCE hInstance; 


HMENU hMenu; 

HWND hwndParent; 
int Cy; 

int CX; 

int y3 

int X3 

LONG Style; 


LPCSTR lpszName; 

LPCSTR IpszClass; 

DWORD dwExStyle; 
} CREATESTRUCT; 


If an application processes this message, it should return 0 to continue creation of 
the window. If the application returns —1, the window will be destroyed and the 
CreateWindowEx or CreateWindow function will return a NULL handle. 


~ CreateWindow, CreateWindowEx, WM_NCCREATE 


WwM_ TLCOLOR : os 


WM_ CTLCOLOR | Bo Se aes ite ae 
hdcChild = (HDC) wParam; : /* child-window display context */ 


hwndChild = (HWND) LOWORD(1Param); /* handle of child window x / 
nCtlType = (int) HIWORD(1Param); /* type of control * / 


The WM_CTLCOLOR message is sent to the parent of a system-defined control 
class or a message box when the control or message box is about to be drawn. The 
following controls send this message: 


Combo boxes 
Edit controls 
List boxes 
Buttons 

Static controls 
Scroll bars 
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Parameters 


Return Value 


Comments 


_ Example 


hdcChild 
Value of wParam. Identifies ii display context for the child window. 


hwndChild 
Value of the low-order word of lParam. Identifies the child window. 


nCtlType | 
Value of the high-order word of /Param. Specifies the type of the control. This 
parameter can be one of the following values: 


Value Meaning 
CTLCOLOR_BTN Button 
CTLCOLOR_DLG Dialog box 
CTLCOLOR_EDIT Edit control 
CTLCOLOR_LISTBOX List box 
CTLCOLOR_MSGBOX Message box 
CTLCOLOR_SCROLLBAR Scroll bar 
CTLCOLOR_STATIC Static control 


If an application processes the WM_CTLCOLOR message, it must return a handle 
to the brush that is to be used for painting the control background or it must return 
NULL. 


To change the text color, the application should call the SetTextColor function 


with the desired red, green, and blue (RGB) values. 


To change the background color of a single-line edit control, the application must 
set the brush handle in both the CTLCOLOR_EDIT and CTLCOLOR_ MSGBOX 
message codes, and the application must call the SetBkColor function in response 
to the CTLCOLOR_EDIT code. | 


The return value from this message has no effect on a button with the 
BS_PUSHBUTTON or BS_DEFPUSHBUTTON style. 


This example creates a green brush and passes the handle of the brush to a single- 


line edit control in response to a WM_CTLCOLOR message: 


static HBRUSH hbrGreen; 


switch(msg) { 
case WM _INITDIALOG: 


/* Create a green brush */ 


hbrGreen = CreateSolidBrush(RGB(Q, 255, Q0)); 
return TRUE; 
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case WM_CTLCOLOR: 
switch(HIWORD(1Param) ) { 
* case CTLCOLOR_EDIT: 


/* Set text to white and background to green */ 


SetTextColor( (HDC) wParam, RGB(255, 255, 255)); 
SetBkColor( (HDC) wParam, RGB(®, 2954g0))4 

return hbrGreen; 

break; 


case CTLCOLOR_MSGBOX: 


/* : | 1, B.38 
* For single-line edit controls, this code must be 

* processed so that the background color of the format 
* rectangle will also be painted with the new color. 


oy, 
return hbrGreen; 
} 
| return (HBRUSH) NULL; 
} 


- See Also SetBkColor 


WM.CUR a 


WM_CUT 
wParam = Q; /* not used, must be zero */ 
]}Param = 


OL; /* not used, must be zero */ 


An application sends a WM_CUT message to an edit control or combo box to de- 
lete (cut) the current selection, if any, in the edit control and copy the deleted text 
to the eippoards in CF_TEXT format. : 


Parameters bes This message has no parameters. 
Return Value The return value is nonzero if this message is sent to an edit control ora Sonibo. 
box. | 


Comments | -AnEM_UN DO message can be sent to Mie edit control to undo the deletion per: 
| te formed by the WM_CUT message: 
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To delete the current selection without placing the deleted text onto the clipboard, 
use the WM_CLEAR message. 


Example | This example sends an EM_SETSEL message to select the entire contents of an 
edit control. It then sends a WM_CUT message to delete the contents of the edit 
control and to copy the deleted text to the clipboard. 


SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, 
EM_SETSEL, @, MAKELONG(Q, -1)); 

SendDlgItemMessage(hdlg, ID_MYEDITCONTROL, 
WM_CUT, @, QOL); 


See Also WM_CLEAR, WM_COPY, WM_PASTE 


WM_DDE_ACK — aa 
| #Finclude <dde.h> | 


WM_DDE_ACK 
wParam = (WPARAM) hwnd; /* handle of posting window . * / 
1Param = MAKELPARAM(wLow, wHigh); /* depending on received message */ 


The WM_DDE_ACK message notifies an application of the receipt and pro- 

cessing of aWM_DDE_INITIATE, WM_DDE_EXECUTE, WM_DDE_DATA, 

WM_DDE_ADVISE, WM_DDE_UNADVISE, or WM_DDE_POKE message, | 
and in some cases, of aWM_DDE_REQUEST message. 


Parameters hwnd | | 
7 Value of wParam. Specifies the handle of the window posting the message. 
wLow 


Value of the low-order word of lParam. Specifies data as follows, depending 
on the message to which the WM_DDE_ACK message is responding: 


Message Parameter Description 

WM_DDE_INITIATE aApplication | —~ Anatom that contains the name of 
| the replying application. 

WM_DDE_EXECUTE wStatus A series of flags that indicate the 


and all other messages 7 status of the response. 


Return Value 


Comments 
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wHigh 
Value of high-order word of lParam. Specifies data as follows, depending on 
the message to which the WM_DDE_ACK message is responding: 


Message Parameter Description 

WM_DDE_INITIATE aTopic An atom that contains the topic with 
which the replying server window is 
associated. 


WM_DDE_EXECUTE hCommands A handle that identifies the data item 
| | containing the command string. 


All other messages altem An atom that specifies the data item 
| for which the response is sent. 


This message does not return a value. 


The wStatus word consists of a DDEACK data structure. The DDEACK structure 


has the following form: 


d#Finclude <dde.h> 


typedef. struct tagDDEACK { /* ddeack */ 
WORD bAppReturnCode:8, 
reserved:6, 
fBusy:1, 
fAck:1; 
} DDEACK; | 


For a full description of this structure, see Chapter 3, “Structures.” 


Posting 


Except in response to the WM_DDE_INITIATE message, the application posts 


the WM_DDE_ACK message by calling the PostMessage function, not the Send- 
Message function. When responding to WM_DDE_INITIATE, the application 
sends the WM_DDE_ACK message by calling SendMessage. 


When acknowledging any message with an accompanying altem atom, the applica- 
tion posting WM_DDE_ACK can either reuse the altem atom that accompanied 
the original message or delete it and create a new one. 


When acknowledging WM_DDE_EXECUTE, the application that posts 
WM_DDE_ACK should reuse the hCommands object that accompanied the origi- 
nal WM_DDE -EXECUTE message. 
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See Also 


WM_DDE_ADVISE 


If an application has initiated the termination of a conversation by posting 
WM_DDE_TERMINATE and is awaiting confirmation, the waiting application 
should not acknowledge (positively or negatively) any subsequent messages sent 
by the other application. The waiting application should delete any atoms or 
shared memory objects received in these intervening messages (but should not de- 
lete the atoms in response to the WM_DDE_ACK message). 


Receiving 


The application that receives WM_DDE_ACK should delete all atoms accompany- 
ing the message. 


If the application receives WM_DDE_ACK in response to a message with an 
accompanying hData object, the application should delete the hData object. 


If the application receives a negative WM_DDE_ACK message posted in reply to 
a WM_DDE_ADVISE message, the application should delete the hOptions object 


posted with the original WM_DDE_ADVISE message. 


If the application receives a negative WM_DDE_ACK message posted in reply to 
a WM_DDE_EXECUTE message, the application should delete the hCommands 
object posted with the original WM_DDE_EXECUTE message. 


_ DDEACK, PostMessage, WM_DDE_ADVISE, WM_DDE_DATA, 


WM_DDE_EXECUTE, WM_DDE_INITIATE, WM_DDE_POKE, 
WM_DDE_REQUEST, WM_DDE_TERMINATE, WM_DDE_UNADVISE 


WM_DDE_ADVISE = oS 


#include <dde.h> 


WM_DDE_ADVISE | : | 
wParam = (WPARAM) hwnd; /* handle of posting window’ */ 
1Param = MAKELPARAM(hOptions, aItem); /* send options and data item */ 


A dynamic data exchange (DDE) client application posts the WM_ DDE_ADVISE 
message to a DDE server application to request the server to eed an n update for 


a data item whenever it changes. 


Parameters 


Return Value 


Comments 
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hwnd | 
Value of wParam. Identifies the sending window. 


hOptions 
Value of the low-order word of /Param. Specifies a handle of a global memory 
object that specifies how the data is to be sent. | 


altem 
Value of the high-order word of /Param. Specifies the vata item being re- 
quested. 


This message does not return a value. 


The global memory object identified by the hOptions parameter consists of a DDE- 
ADVISE data structure. The DDEADVISE data structure has the following form: 


dFinclude <dde.h> 


typedef struct tagDDEADVISE { /* ddeadv */ 
WORD reserved:14, 
fDeferUpd:1, 
| fAckReq:1; 
short  cfFormat; 
} DDEADVISE; 


For a full description of this structure, see Chapter 3, “Structures.” 


If an application supports more than one clipboard format for a single topic and 


item, it can post multiple WM_DDE_ADVISE messages for the topic and item, 
specifying a different mreae format with each message. 


Posting | 
The application posts the WM_DDE_ADVISE message aby calling the Post- 
Message function, not the SendMessage function. 


_ The application allocates hOptions by calling the GlobalAlloc function with the 


GMEM_DDESHARE option. 
The application allocates altem by calling the GlobalAddAtom function. 


If the receiving (server) application responds with a negative WM_DDE_ACK > 
message, the posting (client) application must delete the hOptions object. 
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Receiving 

The application posts the WM_DDE_ACK message to respond positively or nega- 
tively. When posting WM_DDE_ACK, the application can reuse the altem atom 
or delete it and create a new one. If the WM_DDE_ACK message is positive, the 
application should delete the hOptions object; SInET WISE, the application should 
not delete the object. 


See Also DDEADVISE, GlobalAddAtom, GlobalAlloc, PostMessage, 
WM_DDE_DATA, WM_DDE_REQUEST 


WM_DDE_DATA 7 Ey 
#include <dde.h> 


~ WM_DDE_DATA 
wParam = (WPARAM) hwnd; /* handle of posting window * / 
]1Param = MAKELPARAM(hData, aIltem); ./* memory object and data item */ 


A dynamic data exchange (DDE) server application posts a WM_DDE_DATA 
message to a DDE client application to pass a data item to the client or to notify 
the client of the availability of a data item. 


Parameters hwnd 
| Value of wParam. Specifies the handle of the window posting the message. 


hData 
Value of the low-order word of /Param. Identifies the global memory object 
containing the data and additional information. The handle should be set to 
NULL if the server is notifying the client that the data item value has changed 
during a warm link. A warm link is established when the client sends a 
WM_DDE_ ADVISE message with the 2 SDejerUpd bit set. 


altem | 
Value of the high-order word of /Param. Specifies the data item for which data 
or notification 1s sent. 


- Return Value This message does not return a value. 


Comments The global memory object identified by the Data parameter consists of a DDE- — 
o> DATA structure. The DDEDATA structure has the following form: 
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#Finclude <dde.h> 


typedef struct tagDDEDATA { /* ddedat */ 
WORD unused:12, 
fResponse:l, 
fRelease:1, 
reserved:1, 
fAckReq:1; 
short cfFormat; 
BYTE Value[1]; 
} DDEDATA; 


For a full description of this structure, see Chapter 3, “Structures.” 


Posting 
The application posts the WM_DDE_DATA message by calling the PostMessace 
function, not the SendMessage function. 


The application allocates hData by calling the GlobalAlloc function with the 
GMEM_DDESHARE option. 


The application allocates altem by calling the GlobalAddAtom function. 


If the receiving (client) application responds with a negative WM_DDE_ACK 
message, the posting (server) application must delete the hData object. 


If the posting (server) application sets the fRelease member of the DDEDATA 
structure to FALSE, the posting application is responsible for deleting hData upon 
receipt of either a positive or negative acknowledgment. | 


The application should not set both the fAckReq and fRelease members of the 
DDEDATA structure to FALSE. If both members are set to FALSE, it is difficult 
for the posting (server) application to determine when to delete hData. 


Receiving 

If fAckReq is TRUE, the application posts the WM_DDE_ACK message to re- 
spond positively or negatively. When posting WM_DDE_ACK, the application 
can reuse the altem atom or delete it and create a new one. | 


If fAckRegq is FALSE, the ae plicauon deletes the altem atom. | 


If the posting (server) application specified hData as NULL, the receiving ae 
application can request the server to send the actual data by pose a 
WM_DDE_REQUEST message. 


7 After processing a WM_DDE_DATA message in which hData is not NULL, the 
application should delete )Data unless either of the following conditions is true: 
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See Also 


= The fRelease member is FALSE. 


= The fRelease member is TRUE, but the receiving (client) application responds 
with a negative WM_DDE_ACK message. 


DDEDATA, GlobalAddAtom, GlobalAlloc, PostMessage, WM_DDE_ACK, 
WM_DDE_ADVISE, WM_DDE_POKE, WM_DDE_REQUEST 


WM_ DDE EXECUTE ts, tee 


~ Parameters 


Return Value 


Comments 


fHinclude <dde.h> 


WM_DDE_ EXECUTE | 
wParam = (WPARAM) hwnd; /* handle of posting window */ 


_17Param = MAKELPARAM(reserved, hCommands); /* commands to execute * / 


A dynamic data exchange (DDE) client application posts a 
WM_DDE_EXECUTE message to a DDE server application to send a string to 
the server to be processed as a series of commands. The server application is ex- 
pected to posta WM_DDE_ACK message in response. 


hwnd 
Value of wParam. poe the sending window. 


reserved 
Value of the low- order ead of 1/Param. Reserved; must be zero. 


hCommands | 
_ Value of the high-order word of lParam. Identifies a global memory object con- 
taining the command(s) to be executed. 


This message does not return a value. 


The command string is a null-terminated string, consisting of one or more opcode 
strings enclosed in single brackets ([ ]) and separated Dy spaces. 


Each opcode string has the following syntax. The PGT ATCIED® list is optional. 


: opcode parameters 


The opcode is any application- defined single token. It cannot include spaces, com- 
mas, parentheses, or quotation marks. 7 


See Also 
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The parameters list can contain any application-defined value or values. Multiple 
parameters are separated by commas, and the entire parameter list is enclosed in 
parentheses. Parameters cannot include commas or parentheses except inside a 
quoted string. If a bracket or parenthesis character is to appear in a quoted string, it 
must be doubled—for example, “((’’. 


The following are valid command strings: 


[connect ][download(queryl,results.txt)][disconnect] 
[query("sales per employee for each district") ] 
[open("sample.x]m") ][run("rici") ] 


Posting 
The application posts the WM_DDE_EXECUTE message by calling the Post- 
Message function, not the SendMessage function. 


The application allocates hCommands by calling the GlobalAlloc function with 
the GMEM_DDESHARE option. 


When processing a WM_DDE_ACK message posted in reply to a 
WM_DDE_EXECUTE message, the application that posted the original , 
WM_DDE_EXECUTE message must delete the hCommands object sent back in 


~ the WM_DDE_ACK message. 


Receiving 
The application posts the WM_DDE_ACK message to respond positively or nega- 
tively, reusing the hCommands object. 


PostMessage, WM_DDE_ACK 


WM_DDE_INITIATE Kos eo Spa 


deinclude <dde.h> 


WM_DDE_INITIATE 


wParam = (WPARAM) hwnd; _ /* sending window's handle */ 


1Param = MAKELPARAM(aApplication, aTopic); /* application and topic #*/ 


A dynamic data exchange (DDE) client application sends a WM_ DDE_INITIATE 
message to initiate a conversation with server applications responding to the 
SpecInce eppncaon and topic names. 
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Parameters 


Return Value 


Comments 


_ Upon receiving this message, all server applications with names that match the 


aApplication application and that support the aTopic topic are expected to 
acknowledge it (see the WM_DDE_ACK message). 


hwnd 
Value of wParam. Identifies the sending sndey 


aApplication 
Value of the low-order word of /Param. Specifies the name of the application 
with which a conversation is requested. The application name cannot contain 
slash marks (/) or backslashes (\). These characters are reserved for future use 
in network implementations. If aApplicationis NULL, a conversation with all 
applications is requested. 


aTopic | 
Value of the high-order word of lParam. Specifies the topic for which a conver- 
-Sation is requested. If the Opie is NULL, a conversation for all available topics 
is requested. | 


This message does not return a value. 


If aApplicationis NULL, any application can respond. If aTopic is NULL, any 
topic is valid. Upon receiving a WM_DDE_INITIATE request with the aTopic 
parameter set to NULL, an application is expected to send a WM_DDE_ACK mes- 
sage for each of the topics it supports. 


Sending 

The application sends the WM_DDE_INITIATE message by calling the Send- 
Message function, not the PostMessage function. The application broadcasts the 
message to all windows by setting the first parameter of SendMessage to —1, as 
shown: | 


SendMessage(-1, WM_DDE_INITIATE, hwndClient, MAKELONG(aApp, aTopic)); 
If the application has already obtained the window handle of the desired server, it 


can send WM_DDE_INITIATE directly to the server window by passing the 
server’s window handle as the first parameter of SendMessage. 


The application allocates aApplication and atopic by calling GlobalAddAtom. 


When SendMessage returns, the aepicaion dl deletes the Application and aTopic 
atoms. 


See Also 


WM_DDE_POKE 


Parameters 
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Receiving | : 

To complete the initiation of a conversation, the application fstnonds with one or 
more WM_DDE_ACK messages, where each message is for a separate topic. 
When sending a WM_DDE_ACK message, the application creates new 
aApplication and aTopic atoms; it should not reuse the atoms sent with the 
WM_DDE_INITIATE message. 


GlobalAddAtom, SendMessage, WM_DDE_ACK 


dtinclude <dde.h> 


WM_DDE_POKE _ 
wParam = (WPARAM) hwnd; /* handle of posting window */ 
1Param = MAKELPARAM(hData, altem); /* data handle and item * / 


A dynamic data exchange (DDE) client application posts a WM_DDE_POKE 
message to a server application. A client uses this message to request the server to 
accept an unsolicited data item. The server is expected to reply with a 
WM_DDE_ACK message indicating whether it accepted the data item. 


hwnd 


Value of wParam. Specifies the handle of the window posting the message. 


hData 
Value of the low- order word of /Param. Identifies the data being Souad The 
handle identifies a global memory object that contains a DDEPOKE data struc- 
ture. The DDEPOKE structure has the following form: : 


fHinclude <dde.h> 


typedef struct tagDDEPOKE { /* ddepok */ 
| WORD unused:13, 
fRelease:1, 
fReserved:2; 
short cfFormat; — 
BYTE vaca 
} DDEPOKE; 
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For a full description of this structure, see Chapter 3, “Structures.” 


altem 
Value of the high-order word of lParam. Specifies a global atom that identifies 
the data item being offered to the server. 


Return Value This message does not return a value. 


Comments Posting 
| The posting (client) application should do the following: 


= Use the PostMessage function to post the WM_DDE_POKE message. 


= Use the GlobalAlloc function with the GMEM_DDESHARE option to allocate 
memory for the data. 


= Use the GlobalAddAtom fanction to create the atom for the data item. 


= Delete the global memory object if the server application responds with a nega- 
~ tive WM_DDE_ACK message. 


= Delete the global memory object if the client has set the fRelease member of 
the DDEPOKE structure to FALSE and the server responds with either a posi- 
tive or negative WM_DDE_ACK. 


Receiving 
The receiving (server) application should do the following: 


= Post the WM_DDE_ACK message to respond positively or negatively. When 
posting WM_DDE_ACK, reuse the data-item atom or delete it and create a new 
one. | 


= Delete the global memory object after processing WM_DDE_POKE unless 
either the fRelease flag was set to FALSE or the fRelease flag was set to 
TRUE but the server has responded with a negative WM_DDE_ACK message. 


See Also DDEPOKE, GlobalAlloc, PostMessage, WM_DDE_ACK, WM_DDE_DATA 
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WM_DDE_REQUEST __ | ee% 


Parameters | 


Return Value 


. Comments ; 


See Also 


dHinclude <dde.h> 


WM_DDE_REQUEST. | 
wParam = (WPARAM) hwnd; /* handle of posting window */ 
1Param = MAKELPARAM(cfFormat, aIltem); /* clipboard format and item */ 


A dynamic data exchange (DDE) client application posts a WM_DDE_REQUEST | 
message to a DDE server application to request the value of a data item. 


hwnd 
Value of wParam. Identifies the sending window. 


cfFormat 
Value of the low-order word of /Param. Specifies a standard or registered clip- 
board format number. i 


altem 
Value of the high-order word af lParam. Specifies which data item is being re- 
quested from the server. 


This message does not return a value. 


Posting 
The application posts the WM_DDE _REQUEST message by calling the Post- 
Message function, not the SendMessage function. 


The application allocates altem by calling the GlobalAddAtom function. 


Receiving 
If the receiving (server) application can satisfy the request, itresponds witha _ 
WM_DDE_DATA message containing the requested data. Otherwise, it responds 


with a negative WM_DDE_ACK message. 


When responding with either a WM_DDE_DATA or WM_DDE_ACK message, | 
the application can reuse the altem atom or delete it and create a new one. 


GlobalAddAtom, PostMessage, WM_DDE_ACK 


116 WM_DDE_ TERMINATE 


WM_DDE_TERMINATE = Ea 


Parameters 


Return Value 


Comments 


See Also 


#Finclude <dde.h> 
WM_DDE_ TERMINATE 


wParam = (WPARAM) hwnd; /* handle of posting window */ 
1Param = OL; — /* not used, must be zero * / 


A dynamic data exchange (DDE) application (client or server) posts a 


WM_DDE_TERMINATE message to terminate a conversation. 


hwnd | 
Value of wParam. Identifies the sending window. 


This message does not return a value. 


Posting 
The application posts the WM_DDE_TERMINATE message by calling the Post- 
Message function, not the SendMessage function. 


While waiting for confirmation of the termination, the posting application should 
not acknowledge any other messages sent by the receiving application. If the post- 
ing application receives messages (other than WM_DDE_TERMINATE) from the 
receiving application, it should delete any atoms or shared memory objects accom- 
panying the messages. | 


Receiving 
The application responds by posting a WM_DDE_TERMINATE message. 


PostMessage 
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WM_DDE_UNADVISE = OO 
#Finclude <dde.h> 


WM_DDE_UNADVISE 
wParam = (WPARAM) hwnd; /* handle of posting window */— 
1Param = MAKELPARAM(cfFormat, altem); /* clipboard format and item +*/ 


A dynamic data exchange (DDE) client application postsa 
WM_DDE_UNADVISE message to inform a server application that 

the specified item or a particular clipboard format for the item should no 
longer be updated. This terminates the warm or hot link for the specified item. 


Parameters hwnd | 
Value of wParam. Identifies the sending window. 


cfFormat : 
Value of the low-order word of /Param. Specifies the clipboard format of the 
item for which the update request is being retracted. When the cfFormat 
parameter 1s NULL, all active WM_ DDE. _ADVISE conversations for the item 
are to be terminated. 


altem | 

Value of the high-order word of lParam. Specifies the item for which 
the update request is being retracted. When altem is NULL, all active 
WM_DDE_ADVISE conversations associated with the client are to be 


terminated. 
ReturnValue  — This message does not return a value. 


Comments Posting 


The application posts the WM_DDE _UN ADVISE message by calling the Post- 
Message function, not the SendMessage function. 


The application allocates altem by calling the GlobalAddAtom function. 


Receiving 

The application posts the WM_DDE_ACK message to respond positively. or nega- 
tively. When posting WM_DDE_ACK, the application can reuse the altem atom 
or delete it and create a new one. 


SeeAlso ts GlobalAddAtom, PostMessige WM_ DDE_ACK 
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WM_DEADCHAR _e [2x | 


WM_DEADCHAR 
chDeadKey 
dwKkeyData 


= wParam; /* dead-key character */ 

= (DWORD) 1Param; /* key data a / 

The WM_DEADCHAR message is sent when a WM_KEYUP message and a 
WM_KEYDOWN message are translated. It specifies the character value of a 
dead key. A dead key is a key, such as the umlaut (double-dot) character, that is 
combined with other characters to form a composite character. For example, the 
umlaut-O character consists of the dead key, umlaut, and the O key. 


Parameters chDeadKey 
Value of wParam. Specifies the dead-key character value. 


dwKeyData 
Value of /Param. Specifies the repeat count, scan code, extended key, context 
code, previous key state, and key-transition state, as shown in the following 


table: 
Bit Description 
0-15 Specifies the repeat count. The value is the number of times the keystroke 


is repeated as a result of the user holding down the key. 


16-23 Specifies the scan code. The value depends on the original equipment 
manufacturer (OEM). 


24 Specifies whether the key is an extended key, such as a function key ora 
key on the numeric keypad. The value is 1 if it is an extended key; other- 
wise, it is 0. 

25-26  Notused. 

27-28 Used internally by Windows. 


29 Specifies the context code. The value is 1 if the ALT key is held down 
while the key is pressed; otherwise, the value isO. 


30 Specifies the previous key state. The value is 1 if the key is down before 
_ the message is sent, or it is 0 if the key is up. 


31 _ Specifies the key-transition state. The value is 1 if the key is pate re- 
leased, or it is 0 if the key is being pressed. 


Return Value An application should return zero if it processes this message. 


Comments An application typically uses the WM_DEADCHAR message to give the user 
feedback about each key pressed. For example, an application can display the 
accent in the current character position without moving the caret. 


Because there is not necessarily a one-to-one correspondence between keys 
pressed and character messages generated, the information in the high-order word 


See Also 
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of the dwKeyData parameter is usually not useful to applications. The information | 
in the high-order word applies only to the most recent WM_KEYUP or > 
WM_KEYDOWN message that precedes the posting of the character message. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
key and the right CTRL key on the main section of the keyboard; the INS, DEL, _ 
HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the 
numeric keypad; and the division (/) and ENTER keys on the numeric keypad. Some 
other keyboards may support the extended-key bit in the dwKeyData parameter. 


- WM_KEYDOWN 


WM_DELETEITEM | ed 


Parameters | 


Return Value | 


See Also 


WM. DELETEITEM 


idCtl = wParam; /* control identifier */ 
Ipdis = (const DELETEITEMSTRUCT FAR*) 1Param; /* structure * / 


The WM_DELETEITEM message is sent to the owner of an owner-drawn list box 
or combo box when the list box or combo box is destroyed or when items are re- — 
moved by the LB_DELETESTRING, LB_RESETCONTENT, 
CB_DELETESTRING, or CB_RESETCONTENT message. 


idCtl 
Value of wParam. Specifies the identifier of the control that sent the 
WM_DELETEITEM message. | 


lpdis 
Value of [Param. Points to a DELETEITEMSTRUCT structure that contains 
information about the item deleted from the list box. The DELETELTEM: 
STRUCT structure has the following form: 


typedef struct tagDELETEITEMSTRUCT { /* deli */ 
UINT CtlType; | : 
UINT CtlID; 
UINT itemID; 
~HWND hwndItem; 
DWORD itemData; 
~} DELETEITEMSTRUCT ; 


An application should return TRUE if it processes | this message. 


CB _DELETESTRING, CB _RESETCONTENT, LB. _DELETESTRING, | 
LB _RESETCONTENT 
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WM_DESTROY a0 


The WM_DESTROY message is sent when a window is being destroyed. It is sent 
to the window procedure of the window being destroyed after the window is re- 
moved from the screen. 


This message is sent first to the window being destroyed and then to the child win- 
dows as they are destroyed. During the processing of the WM_DESTROY mes- 
sage, it can be assumed that all child windows still exist. 


Parameters This message has no parameters. 
Return Value An application should return zero if it processes this message. 
Comments If the window being destroyed is part of the clipboard-viewer chain (set by calling 


the SetClipboard Viewer function), the window must remove itself from the 
clipboard-viewer chain by calling the ChangeClipboardChain function before 
returning from the WM_DESTROY message. 


Example This svample processes the WM_ DESTROY message by calling the PostQuit- 
Message function: 


case WM_DESTROY: 
PostQuitMessage(Q@); 
return @L; 


See Also ChangeClipboardChain, Destroy Window, PostQuitMessage, pereripboara: 
Viewer, WM_CLOSE 


WM_DESTROYCLIPBOARD ax] 


WM_DESTROYCLIPBOARD 


The WM_DESTROYCLIPBOARD message is sent to the clipboard owner when 
the clipboard is emptied by a call to the EmptyClipboard function. | 


Parameters — This message has no parameters. 


Return Value 


See Also 


WM_DRAWCLIPBOARD 121° 


An application should return zero if it processes this message. 


EmptyClipboard 


WM_DEVMODECHANGE [2x | 


Parameters - 


Return Value 


Comments | 


See Also 


WM_DEVMODECHANGE 
TpszDev = (LPCSTR) ]Param; /* address of device name */ 


The WM_DEVMODECHANGE message is sent to all top-level windows when 
the default device-mode settings have changed. 


lpszDev | 
Value of /Param. Points to the device name eapecuned in the Windows initializa- 
tion file, WIN.INI. 


An application should return zero if it processes this message. 


Applications that receive this message may reinitialize their device-mode settings. 
Applications that use the ExtDeviceMode function to save and restore device set- 


tings typically do not process this message. 


This message is not sent when the user changes the default printer from Control 
Panel. In this case, a WM_WININICHANGE message is generated. 


ExtDeviceMode, WM_WININICHANGE 


WM_DRAWCLIPBOARD * ax] 


WM_DRAWCLIPBOARD 


The WM_DRAWCLIPBOARD message is sent to the first window in the 


_clipboard-viewer chain when the contents of the clipboard change. Only applica- 


tions that have joined the clipboard-viewer chain by calling the SetClipboard- 
Viewer function need to process this message. | | 
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Parameters This message has no parameters. 


Return Value An application should return zero if it processes this message. 
Comments Each window that receives the WM_DRAWCLIPBOARD message should call 


the SendMessage function to pass the message on to the next window in the clip- 
board-viewer chain. The handle of the next window is returned by the Set- 
Clipboard Viewer function; the handle may be modified in response to a 
WM_CHANGECBCHAIN message. 


See Also SendMessage, SetClipboard Viewer, WM_CHANGECBCHAIN 


WM_DRAWITEM 


-WM_DRAWITEM 
jdCtl (int) wParam; /* control identifier */ 
lpdis (const DRAWITEMSTRUCT FAR*) 1Param; /* structure * / 


The WM_DRAWITEM message is sent to the owner of an owner-drawn button, 
combo box, list box, or menu when a visual aspect of the button, combo box, list 
box, or menu has changed. 


Parameters idCtl 


Value of wParam. Specifies the identifier of the control that sent the | 
WM_DRAWITEM message. This parameter is zero if the message was sent by 
a menu. 


lpdis 
Value of Param. Points toa DRAWITEMSTRUCT structure that contains in- 
formation about the item to be drawn and the type of drawing required. The 
DRAWITEMSTRUCT structure has the following form: 


typedef struct tagDRAWITEMSTRUCT { /* ditm */ 
UINT CtlType; | 
UINT CtlID; 
UINT itemID; 
UINT . itemAction; 
UINT itemState; 
HWND hwndIten; 
HDC =hDC; 
RECT rcItem; 
DWORD itemData; 
} DRAWITEMSTRUCT; 


Return Value 


Comments 


Example 


See Also 
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An application should return TRUE if it processes this message. 


The itemAction member of the DRAWITEMSTRUCT structure defines the 
drawing operation that is to be performed. The data in this member allows the 
owner of the control to determine what drawing action is required. 


Before returning from processing this message, an application should ensure that 
the device context identified by the hDC member of the DRAWITEMSTRUCT 
structure is in the default state. — 


This example shows how to process the WM_DRAWITEM message: 


LPDRAWITEMSTRUCT Ipdis; 


case WM_DRAWITEM: 
Tpdis = (DRAWITEMSTRUCT FAR*) 1Param; 


switch (lpdis->itemAction) { 

case ODA_DRAWENTIRE: 
/* Redraw the entire control or menu. */ 
recur TRUE; 

case ODA_SELECT: 
/* Redraw to reflect current selection state. */ 
eecunn TRUE; 

case ODA_FOCUS: 
/* Redraw to reflect current focus state. */ 
return TRUE; 


} 
break; 


WM_COMPAREITEM, WM_DELETEITEM, WM_INITDIALOG, 
WM_MEASUREITEM 
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WM_DROPFILES - ns En 


WM_DROPFILES 
hDrop = (HANDLE) wParam; /* handle of internal drop structure */ 


The WM_DROPFILES message is sent when the user releases the left mouse but- 
ton over the window of an application that has registered itself as a recipient of 
dropped files. 


Parameters hDrop 
Value of wParam. Identifies an internal data structure describing the dropped 
files. This handle is used by the DragFinish, DragQueryFile, and DragQuery- 
Point functions to retrieve information about the dropped files. 


Return Value An application should return zero if it processes this message. 


See Also DragAcceptFiles, DragFinish, DragQueryFile, DragQueryPoint 


WM_ENABLE ts _ a 


WM_ ENABLE 
fEnabled = (BOOL) wParam; /* the enabled/disabled flag */ 


The WM_ENABLE message is sent when an application changes the enabled state 
of a window. It is sent to the window whose enabled state is changing. This mes- 
Sage is sent before the EnableWindow function returns but after the enabled State 
(WS_DISABLE style bit) of the window has changed. 


Parameters fEnabled 
Value of wParam. Specifies whether the window has been enabled or disabled. 
This parameter is TRUE if the window has been enabled; it is FALSE if the 
window has been disabled. 


Return Value An application should return zero if it processes this message. 


See Also | EnableWindow 
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WM_ENDSESSION Pax] 


WM_ENDSESSION 
fEndSession = (BOOL) wParam; /* end-session flag */ 


The WM_ENDSESSION message is sent to an application that has returned 
a nonzero value in response to a WM_QUERYENDSESSION message. The 
WM_ENDSESSION message informs the application whether the session is 
actually ending. 


Parameters fEndSession 
| Value of wParam. Specifies whether the session is being ended. It is TRUE if 
the session is being ended; otherwise, it is FALSE. 


Return Value An application should return zero if it processes this message. 


Comments If the fEndSession parameter is TRUE, Windows can terminate any time after all. 
“ applications have returned from processing this message. Therefore, an application 
should perform all tasks required for termination before returning from this mes- 

sage. | 


The application does not need to call the Destroy Window or PostQuitMessage 
function when the session is ending. 


See Also Destroy Window, ExitWindows, PostQuitMessage, 
WM_QUERYENDSESSION 


WM_ENTERIDLE a 


WM_ENTERIDLE xe 
fwSource = wParam; _ /* jdle-source flag ok] 
hwndDig = (HWND) LOWORD(1Param); /* handle of dialog box or window */ 


The WM_ENTERIDLE message informs an application’s main window proce- 
dure that a modal dialog box or a menu is entering an idle state. A modal dialog 

box or menu enters an idle state when no messages are waiting in its queue after it — 
has processed one or more previous messages. 


Parameters  fwSource 
Value of wParam. Specifies whether the message is the result of a dialog box 
or a menu being displayed. This parameter can be one of the following values: 
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Return Value 
Comments 


See Also 


WM_ERASEBKGND 


Parameters 
Return Value 


Comments 


Value Description 
MSGF_DIALOGBOX The system is idle because a dialog box is being dis- 
played. 
MSGF_MENU The system is idle because a menu is being displayed. 
_hwnaDig 


Value of the low-order word of /Param. Identifies the dialog box (if fwSource 
is MSGF_DIALOGBOX) or the handle of the window containing the displayed 
menu (if fwSource is MSGF_MENU). 


An application should return zero if it processes this message. 
The DefWindowProc function returns zero when it processes this message. 


DefWindowProc 


[ 2x | 


WM_ ERASEBKGND 
hdc = (HDC) wParam; /* device-context handle “hb 


The WM_ERASEBKGND message is sent when the window background needs 
to be erased (for example, when a window is resized). It is sent to prepare an in- 
validated region for painting. 


hdc | 
Value of wParam. Identifies the device context. 


An application should return nonzero if it erases the background; otherwise, it 
should return zero.. 


‘The DefWindowProc function erases the background by using the class back- 


ground brush specified by the hbrbackground member of the WNDCLASS struc- 
ture. 


If the hbrHackground member is NULL, the ‘pplication should process the 
WM_ERASEBKGND message and erase the background color. When processing 


_ the WM_ERASEBKGND message, the application must align the origin of the in- 


tended brush with the window coordinates by first calling the UnrealizeObject 


| function for the brush and then selecting the brush. 


See Also 
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Windows computes the background by using the MM_TEXT mapping mode. If 


the device context is using any other mapping mode, the area erased may not be 


within the visible part of the client area. 


UnrealizeObject, WM_ICONERASEBKGND 


WM_FONTCHANGE Pax] 


Parameters 
Return Value 


Comments 


See Also 


WM_FONTCHANGE 
wParam = Q; /* not used, must be zero */ 


1Param = QL; /* not used, must be zero */ | 


An application sends the WM_FONTCHANGE message to all top-level windows 


in the system after changing the pool of font resources. 

This message has no parameters. 

An application should return Zer0 if it processes this message. 

An application that adds or removes fonts from the system (for example, by using 


the AddFontResource or RemoveF ontResource function) should send this mes- 
sage to all top-level windows. | 


To send the WM_FONTCHANGE message to all top-level windows, an applica- 
tion can call the SendMessage function with the hwnd parameter set to OXFFFF. 


AddFontResource, RemoveFontResource, SendMessage 


WM_GETDLGCODE =i ax 


WM_GETDLGCODE 


The WM_GETDLGCODE message is sent to the dialog box procedure associated 
with a control. Normally, Windows handles all arrow-key and TAB-key input to the 
control. By responding to the WM_GETDLGCODE message, an application can 
take control of a particular type of input and process the input itself. 


128 | WM_GETFONT 


Parameters This message has no parameters. 
Return Value The return value is one or more of the following values, indicating which type of 
| input the application processes: 
Value | Meaning 
_ DLGC_DEFPUSHBUTTON _ Default push button 
\ DLGC_HASSETSEL _ EM_SETSEL messages 
°F DLGC_PUSHBUTTON Push button 
| DLGC_RADIOBUTTON _ Radio button 
DLGC_WANTALLKEYS All keyboard input 
DLGC_WANTARROWS Arrow keys 
DLGC_WANTCHARS WM_CHAR messages 
DLGC_WANTMESSAGE All keyboard input (the application passes this 
message on to the control) 
DLGC_WANTTAB TAB key 
Comments Although the DefWindowProc function always returns zero in response to the 


WM_GETDLGCODE message, the window procedures for the predefined control 
classes return a code appropriate for each class. 


_ The WM_GETDLGCODE message and the returned values are useful only with 
user-defined dialog box controls or standard controls modified by subclassing. 


WM_GETFONT — 


WM_GETFONT 
wParam = Q@; /* not used, must be zero */ 
]Param = @L; /* not used, must be zero */ 


An application sends a WM_GETFONT message to a control to retrieve the font 
with which the control is currently drawing its text. 


Parameters This message has no parameters. 


Return Value The return value is the handle of the font used aby the control, or it is NULL if the 
oe control i Is using the enn font. 


See Also WM_SETFONT 
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WM_GETMINMAXINFO [2x | 
WM_GETMINMAXINFO 
'pmmi = (MINMAXINFO FAR#) lParam; /* address of structure */ 


The WM_GETMINMAXINFO message is sent to a window whenever Windows 
needs the maximized position or dimensions of the window or needs the maxi- 
mum or minimum tracking size of the window. The maximized size of a window 
is the size of the window when its borders are fully extended. The maximum track- 
ing size of a window is the largest window size that can be achieved by using the 
borders to size the window. The minimum tracking size of a window is the small- 
est window size that can be achieved by using the borders to size the window. 


Windows fills ina MINMAXINFO data structure, specifying default values for 
the various positions and dimensions. The application may change these values if 
it processes this message. 


Parameters | lpmmi 
Value of /Param. Points toa MINMAXINFO data structure. The MINMAX- 
INFO structure has the following form: 


typedef struct tagMINMAXINFO { /* mmi */ 
POINT ptReserved; 
POINT ptMaxSize; 
POINT ptMaxPosition; 
POINT ptMinTrackSize; 
POINT ptMaxTrackSize; 
} MINMAXINFO; 


Return Value An application should return zero if it processes this message. 
Example __. - This example processes a WM_GETMINMAXINFO message and sets the min- 
_ imum tracking width of the window to 200 and the minimum tracking height of 

the window to 500: . 


_MINMAXINFO FAR* 1pmmi; 


case WM_GETMINMAXINFO: 
Tpmmi = (MINMAXINFO FAR*) 1Param; 
Tpmmi->ptMinTrackSize.x = 200; 
lpmmi->ptMinTrackSize.y = 50Q@; 


break; 
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WM_GETTEXT 


WM_GETTEXT | 
wParam = (WPARAM) cchTextMax; /* number of bytes to copy * / 
]Param = (LPARAM) lpszText; /* address of buffer for text */ 


An application sends a WM_GETTEXT message to copy the text that corresponds 
to a window into a buffer provided by the caller. 


Parameters cchTextMax 
Value of wParam. Specifies the maximum number of bytes to be copied, includ- 
ing the terminating null character. 


lpszText 
Value of /Param. Points to the buffer that 1s to receive the text. 


Return Value The return value is the number of bytes copied. It is CB_ERR if the message I iS 
sent to a combo box that has no edit control. 


Comments For an edit control, the text to be copied is the contents of the edit control. For a 
: | combo box, the text is the contents of the edit-control (or static-text) portion of the 
combo box. For a button, the text is the button name. For other windows, the text 
is the window title. To copy the text of an item in a list box, an application can use 
the LB_GETTEXT message. 


When the WM_GETTEXT message is sent to a static control with the SS_ICON 
style, the handle of the icon will be returned in the first two bytes of the buffer 
pointed to by /pszText. This is true only if the WM_SETTEXT message has been 
used to set the icon. 


Example This example copies text from an edit control to a buffer: 


HWND hwndMyEdit; 
char szBuffer[32]; 


hwndMyEdit = GetDlgItem(hdlg, ID_MYEDITCONTROL); 


SendMessage(hdlg, WM_GETTEXT, sizeof(szBuffer), 
(LPARAM) ((LPSTR) szBuffer)); 


See Also LB_GETTEXT, WM_GETTEXTLENGTH, WM_SETTEXT 
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WM_GETTEXTLENGTH aa 


WM_GETTEXTLENGTH 
wParam = Q; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application sends a WM_GETTEXTLENGTH message to determine the 
length, in bytes, of the text associated with a window. The length does not include 
the terminating null character. 


Parameters This message has no parameters. 


Return Value The return value is a word specifying the length, in bytes, of the text. 
Comments For an edit control, the text to be copied is the contents of the edit control. For a 


combo box, the text is the contents of the edit-control (or static-text) portion of the 
combo box. For a button, the text is the button name. For other windows, the text 
is the window title. To determine the length of an item in a list box, an application 
can use the LB_GETTEXTLEN message. 


Example 3 This example enables the push button in a dialog box if the user has entered text in 
an edit control in the dialog box: 


case ID_MYEDITCONTROL: | , 
if CHIWORD(1Param) == EN CHANGE) 
EnableWindow(GetDlgItem(hdlg, IDOK), 
(BOOL) SendMessage(LOWORD(1Param), 
WM_GETTEXTLENGTH, @, OL)); 
return TRUE; ) 


See Also | LB_GETTEXTLEN, WM_GETTEXT 
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WM_HSCROLL ‘ie 


WM_HSCROLL 
wScrol1lCode = wParam; /* scroll bar code * / 
nPos = LOWORD(1Param) ; /* current position of scroll box */ 


hwndCtl = (HWND) HIWORD(1Param); /* handle of the control * / 


The WM_HSCROLL message is sent to a window when the user clicks the win- 
dow’s horizontal scroll bar. 


_ Parameters wScrollCode 
| Value of wParam. Specifies a scroll bar code that indicates the user’s scrolling 
request. This parameter can be one of the following values: 


Value Description 
SB_LEFT Scroll to far left. 
SB_LINELEFT Scroll left. 
SB_LINERIGHT Scroll right. 
SB_PAGELEFT Scroll one page left. 
SB_PAGERIGHT _- Scroll one page right. 
SB_RIGHT Scroll to far right. 


SB_THUMBPOSITION Scroll to absolute position. The current position is 
specified by the nPos parameter. 


SB_THUMBTRACK Drag scroll box (thumb) to specified position. The cur- 
rent position is specified by the nPos parameter. 


nPos | 
Value of the low-order word of /Param. Specifies the current position of the 
scroll box if the wScrollCode parameter is SB_THUMBPOSITION or 
SB_THUMBTRACK; otherwise, the nPos parameter is not used. 


hwndCil 
Value of the high-order word of /Param. Identifies the control if 
WM_HSCROLL is sent by a scroll bar. If WM_HSCROLL is sent as a result of © 
the user clicking a pop-up window’s scroll bar, the high-order word is not used. 


Return Value An application should return zero if it processes this message. 


Comments The SB_THUMBTRACK scroll bar code typically is used by applications that 
give some feedback while the scroll box is being dragged. 


If an application scrolls the contents of the window, it must also reset the position 
of the scroll box by using the SetScrollPos function. 


See Also SetScrollPos, WM_VSCROLL 
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WM_HSCROLLCLIPBOARD  ——agg 


_ Parameters 


Return Value | 


Comments 


See Also 


WM_HSCROLLCLIPBOARD 


hwndCBViewer = (HWND) wParam; /* handle of clipboard viewer */ 
wScrol|]Code = LOWORD(1Param); /* scroll bar code * / 
nPos. = (int) HIWORD(1Param); /* scroll box position —ok/ 


The WM_HSCROLLCLIPBOARD message is sent by the clipboard viewer to the 
clipboard owner when the clipboard data has the CF_LOWNERDISPLAY format 
and an event occurs in the clipboard viewer’s horizontal scroll bar. The owner 
should scroll the clipboard image, invalidate the appropriate section, and update 
the scroll bar values. 


hwndCBViewer | 
_ Value of wParam. Identifies a clipboard-viewer window. 


wScrollCode 
Value of the low-order word of /Param. Specifies a scroll bar code. This 
parameter can be one of the following values: 


Value Description 
SB_BOTTOM Scroll to lower right. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_LINEUP Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 
SB_PAGEUP Scroll one page up. — 
SB_THUMBPOSITION __ Scroll to absolute position. 
SB_TOP Scroll to upper left. 

nPos 


Value of the high- order word of /Param. Specifies the scroll box position if the 
_ scroll bar code is SB_THUMBPOSITION; otherwise, the high- order word of 
_ |Parami is not used. 


An application should return zero if it aie this ee 


The clipboard owner should use the InvalidateRect function or repaint as needed. 
The scroll bar position should also be reset. : 


InvalidateReet, WM_VSCROLLCLIPBOARD - 
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WM_ICONERASEBKGND 


WM_ ICONERASEBKGND 
hdc = (HDC) wParam; /* device-context handle */ 


The WM_ICONERASEBKGND message is sent to a minimized (iconic) window 
when the background of the icon must be filled before painting the icon. A win- 
dow receives this message only if a class icon is defined for the window; other- 
wise, WM_ERASEBKGND is sent. 


Parameters hdc 
7 Value of wParam. Identifies the device context of the icon. 


Return Value An application should return zero if it processes this message. 


Comments The DefWindowProc function fills the icon background with the background 
brush of the parent window. 


See Also DefWindowProc, WM_ERASEBKGND 
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WM_INITDIALOG 
hwndFocus = (HWND) eParant: /* handle of control for focus */ 
dwData = 1|Param; /* application-specific data  ¥*/ 


The WM_INITDIALOG message is sent to a dialog box procedure nea 
before the dialog box is displayed. 


Parameters hwndFocus | 
Value of wParam. Identifies the first control in the dialog box that can be given 
the input focus. Usually, this is the first control in the dialog box with the 
WS_TAB STOP Se 


dwData 
Value of /Param. Specifies application-specific data that was passed by the 
function used to create the dialog box if the dialog box was created by one of 
the following functions: 


CreateDialogParam — 
DialogBoxIndirectParam 
DialogBoxParam 
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Return Value _ An application should return nonzero to set the input focus to the control identified 
? by the hwndFocus parameter. An application should return zero if the dialog box 
procedure uses the SetFocus function to set the input focus to a different control 
in the dialog box. 3 


Example This example changes the font used by controls in a dialog box to a font that is not 
bold. 


HFONT hDlgFont; 
LOGFONT 1Font; 


case WM _INITDIALOG: 
/* Get dialog box font and create version that is not bold. */ 


hDigFont = (HFONT) NULL; | , 
if ((hDlgFont = (HFONT) SendMessage(hdlg, WM_GETFONT, @, @L))) { 
if (GetObject(hDlgFont, sizeof(LOGFONT), (LPSTR) “&lFont)) { 
1Font.1fWeight = FW_NORMAL; 
if (hDlgFont = CreateFontIndirect((LPLOGFONT) &lFont)) { 
SendDlgItemMessage(hdlg, ID_CTRL1, WM_SETFONT, 
hDigFont, OL); 
SendDigItemMessage(hdlg, 1D. CTRL2, WM_ SETFONT, 
hDigFont, OL); 


. /* Set font for remaining controls. */. 


seoy 
} 
return TRUE; 


See Also | | CreateDialogParam, DialogBoxIndirectParam, DialogBoxParam, SetFocus | 


WM_INITMENU arn 


WM_INITMENU , . 
— hmenulnit = (HMENU) wParam; /* handle of menu to initialize */ — 


_ The WM_INITMENU message is sent when a menu is about to become active. It 
occurs when the user clicks an item on the menu bar or presses a menu key. This 
allows an application to modify the menu before it is displayed. 
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Parameters 


Return Value 


Comments 


See Also 


hmenuInit 
Value of wParam. Identifies the menu to be initialized. 


An application should return zero if it processes this message. 


This message is sent only when a menu is first accessed; only one 
WML_INITMENU message is generated for each access. This means, for example, 
that moving the mouse across several menu items while holding down the button 
does not generate new messages. WM_INITMENU does not provide information 
about menu items. 


WM_INITMENUPOPUP 


WM_INITMENUPOPUP [2x] 


Parameters 


Return Value 


WM_ INI TMENUPOPUP 


hmenuPopup = (HMENU) wParam; /* handle of pop-up menu */ 
nIndex = (int) LOWORD(1Param); /* index of pop-up menu */ 


fSystemMenu = (BOOL) HIWORD(1Param); /* System-menu flag 2 / 


The WM_INITMENUPOPUP message is sent when a pop-up menu is about to be- 
come active. This allows an application to modify the pop-up menu before it is dis- 
played, without changing the entire menu. 


hmenuPopup 
Value of wParam. Identifies the pop- up menu. 


nIndex 
Value of the low-order word of /Param. Specifies the index of the pop- By menu 
in the main menu. 


fSystemMenu 
Value of the high-order word of /Param. Specifies a nonzero value if the pop- 
up menu is the System menu (sometimes referred to as the Control menu); 
otherwise, this parameter is zero. 


An application should return zero if it processes this message. 
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Example This example initializes the items in a pop-up menu: 


int nCount; 
WORD witen; 
UINT ulID; 


case WM_INITMENUPOPUP: 
nCount = GetMenuItemCount(wParam) ; 
for (wltem = @; wiltem < nCount; witem++) { 
uID = GetMenuItemID(wParam, witem); 


. /* Initialize menu items. */ 


} 
break; 


See Also ~ WM_INITMENU 


WM_KEYDOWN az] 


WM_KEYDOWN 
wVkey = wParam; /* virtual-key code */ 
dwkeyData = 1Param; /* key data x / 


The WM_KEYDOWN message is sent when a nonsystem key is pressed. A non- 
system key is a key that is pressed when the ALT key is not pressed, or itis a key | 
that is pressed when a window has the input focus. 


Parameters wVkey 
Value of wParam. Specifies the virtual-key code of the given key. 


dwKeydata a 
Value of /Param. Specifies the repeat count, scan code, extended key, context 
code, previous Key state, and key-transition state, as shown in the following » 


table: . 
Bit Description 
0-15 Specifies the repeat count. The value is the number of times the keystroke 
is repeated as a result of the user holding down the key. 
16-23 Specifies the scan code. The value depends on the original equipment 
manufacturer (OEM). | 
24 Specifies whether the key is an extended key, such as a function key or a 


key on the numeric keypad. The value is 1 if it is an extended key; other- 
wise, it is 0. 
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Bit Description 


25-26 Not used. | 
27-28 Used internally by Windows. 


29 Specifies the context code. The value is 1 if the ALT key is held down 
| while the key is pressed; otherwise, the value is 0. 


30 Specifies the previous key state. The value is 1 if the key is down before 
the message is sent, or it is 0 if the key is up. 
3] Specifies the key-transition state. The value is 1 if the key is being re- 


leased, or it is 0 if the key is being a 


Fora WM_KEYDOWN message, the value of bit 29 (context coer) is 0 and 
the value of bit 31 (key-transition state) is 0. 


Return Value An application should return zero if it processes this message. 


Comments Because of the autorepeat feature, more than one WM_KEYDOWN message may 
occur before a WM_KEYUP message is sent. The previous key state (bit 30) can 
be used to determine whether the WM_KEYDOWN message indicates the first 
down transition or a repeated down transition. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
key and the right CTRL key on the main section of the keyboard; the INS, DEL, 
HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the 
numeric keypad; and the division (/) and ENTER key on the numeric keypad. Some 
other keyboards may support the extended-key bit in the dwKeyData parameter. 


See Also WM_CHAR, WM_KEYUP 


WM_KEYUP ei : aa] 


WM_KEYUP 
wVkey = wParam; /* virtual-key code */ 
dwkeyData = 1Param; /* key data * / 


The WM_KEYUP message is sent when a nonsystem key is released. A non- 
system key is a key that is pressed when the ALT key is not pressed, or it is a key 
that is pressed when a window has the input focus. 


Parameters 


Return Value 


Comments 


See Also 


wVkey 


WM_KEYUP 


Value of wParam. Specifies the virtual-key code of the given key. 


dwKeyData 
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Value of /Param. Specifies the repeat count, scan code, extended key, context 
code, previous key state, and key-transition state, as shown in the following 


table: 
Bit 
0-15 
16-23 
24 
25-26 

* 27-28 
29 


30 


31 


Description 
Specifies the repeat count. The value is the number of times the keystroke 
is repeated as a result of the user holding down the key. 


Specifies the scan code. The value depends on the original equipment 
manufacturer (OEM). 


Specifies whether the key is an extended key, such as a function key or a 
key on the numeric keypad. The value is 1 if it is an extended key; other- 
wise, it is 0. 

Not used. 

Used internally by Windows. 

Specifies the context code. The value is 1 if the ALT + key j is held down 
while the key is pressed; otherwise, the value is 0. 

Specifies the previous key state. The value is 1 if the key is down before 
the message is sent, or it is 0 if the Key 1s up. 

Specifies the key-transition state. The value is 1 if the key i is being re- 
leased, or it is 0 if the key is being pressed. 


For a WM_KEYUP message, the value of bit 29 (context code) is 0 and the 
value of bit 31 (Key-transition state) is 1. 


An application should return zero if it processes this message. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
Key and the right CTRL key on the main section of the keyboard; the INS, DEL, 
HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the 

numeric keypad; and the division (/) and ENTER Keys on the numeric keypad. Some. 
other keyboards may support the extended-key bit in the dwKeyData parameter. 


WM_CHAR, WM_KEYDOWN | 


* 
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WM_KILLFOCUS 


WM_KILLFOCUS 


hwndGetFocus = (HWND) IParam; 


[ 2.x | 


/* handle of window receiving focus */ 


The WM _KILLFOCUS message is sent pee before a window loses the 


input focus. 


Parameters hwndGetFocus 


Value of wParam. Identifies the window that receives the input focus. (This 
parameter may be NULL.) 


Return Value 
Comments 


See Also 


WM_LBUTTONDBLCLK 


WM_LBUTTONDBLCLK 
fwkeys = wParam; 


xPos = LOWORD(1Param); 
yPos = HIWORD(1Param) ; 


An application should return zero if it processes this message. 
If an application is displaying a caret, the caret should be destroyed at this point. 


SetFocus, WM_SETFOCUS 


/* key flags * / 
/* horizontal position of cursor */ 
/* vertical position of cursor * / 


The WM_LBUTTONDBLCLK message is sent when the user double-clicks the 


left mouse button. 


Parameters fwKeys 


Value of wParam. Indicates whether various ral keys are down. This 
parameter can be any combination of the following values: 


Value 


MK_CONTROL 
MK_LBUTTON 
MK_MBUTTON 
MK_RBUTTON 
MK_SHIFT 


Description 


Set if CTRL key is down. 

Set if left button is down. 
Set if middle button is down. 
Set if right button is down. 
Set if SHIFT key is down. 


Return Value 


Comments 


See Also 


WM_LBUTTONDOWN 


Parameters 
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xPos | 
Value of the low-order word of lParam. Specifies the x-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


yPos | 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


An application should return zero if it processes this message. 


Only windows that have the CS_DBLCLKS class style can receive 
WM_LBUTTONDBLCLK messages. Windows generates a 
WM_LBUTTONDBLCLK message when the user presses, releases, and again 
presses the left mouse button within the system’s double-click time limit. Double- 
clicking the left mouse button actually generates four messages: a 
WM_LBUTTONDOWN message, a WM_LBUTTONUP message, the 
WM_LBUTTONDBLCLK message, and another WM_LBUTTONUP message. 


WM_LBUTTONDOWN, WM_LBUTTONUP 


WM_LBUTTONDOWN oe, 
fwkeys = wParam; /* key flags ; * / 


xPos = LOWORD(1Param); /* horizontal position of cursor */ 
yPos = HIWORD(1Param); /* vertical position of cursor */ 


The WM_LBUTTONDOWN message is sent when the user presses the left 
mouse button. | 


fwKeys 
Value of wParam. Specifies whether various virtual keys are down. This 
parameter can be any combination of the following values: 


Value Description 


MK_CONTROL Set if CTRL key is down. 
MK_MBUTTON Set if middle button is down. 
MK _RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


xPos oe : 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 
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yPos | | 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. | 
Return Value An application should return zero if it processes this message. 


See Also WM_LBUTTONDBLCLK, WM_LBUTTONUP 


WM_LBUTTONUP _ irra 


WM_LBUTTONUP 


fwkeys = wParam; /* key flags * / 
— XPos = LOWORD(1Param) ; /* horizontal position of cursor */ 
yPos = HIWORD(1Param) ; /* vertical position of cursor */ 


The WM_LBUTTONUP message is sent when the user releases the left mouse 
button. 


Parameters — fwKeys 
Value of wParam. Indicates whether various virtual keys are down. 
This parameter can be any combination of the following values: 


Value Description 
MK_ CONTROL Set if CTRL key is down. 
MK_MBUTTON Set if middle button is down. 


MK_RBUTTON Set if right button is down. 
MK_SHIFT | Set if SHIFT key is down. 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 

_ sor. The coordinate is relative to the upper-left corner of the window. 

yPos | | 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


Return Value | An application should return zero if it processes this message. 


See Also WM_LBUTTONDBLCLK, WM_LBUTTONDOWN 
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WM_MBUTTONDBLCLK | Pax] 


WM_MBUTTONDBLCLK 


fwkeys = wParam; /* key flags * / 
xPos = LOWORD(1Param) ; /* horizontal position of cursor */ 
yPos = HIWORD(1Param) ; /* vertical position of cursor ¥*/ 


The WM_MBUTTONDBLCLK message is sent when the user double-clicks the 
middle mouse button. 


Parameters fwKeys , 
Value of wParam. Indicates whether various virtual keys are down. This 
parameter can be any combination of the following values: 


Value Description 


MK_CONTROL Set if CTRL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON Set if middle button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT | Set if SHIFT key is down. 


xPos 
_ Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


yPos | 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


Return Value An application should return zero if it processes this message. 


Comments Only windows that have the CS_DBLCLKS class style can receive 
WM_MBUTTONDBLCLK messages. Windows generates a 
WM_MBUTTONDBLCLK message when the user presses, releases, and again 
presses the middle mouse button within the system’s double-click time limit. 
Double-clicking the middle mouse button actually generates four messages: a 
WM_MBUTTONDOWN message, a WM_MBUTTONUP message, the 
WM_MBUTTONDBLCLK message, and another WM_MBUTTONUP message. 


See Also WM_MBUTTONDOWN, WM_MBUTTONUP 
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WM_MBUTTONDOWN 


Parameters 


Return Value 


See Also 


WM_MBUTTONUP 


WM_MBUTTONDOWN : 
fwkeys = wParam; /* key flags * / 


xPos = LOWORD(1Param); /* horizontal position of cursor */ 
yPos = HIWORD(1Param) ; /* vertical position of cursor  ¥*/ 


The WM_MBUTTONDOWN message is sent when the user presses the middle 
mouse button. 


fwKeys | me 
Value of wParam. Indicates whether various virtual keys are down. This 
parameter can be any combination of the following values: 
Value Description 


MK_CONTROL _ Setif CTRL key is down. 
MK_LBUTTON _ Setif left button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


yPos 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 

An application should return zero if it processes this message. 


WM_MBUTTONDBLCLK, WM_MBUTTONUP 


WM_MBUTTONUP : ‘ 
fwkeys = wParam; /* key flags * / 


xPos = LOWORD(1Param); /#* horizontal position of cursor */ 
yPos = HIWORD(1Param) ; /* vertical position of cursor * / 


The WM_MBUTTONUP message is sent when the user releases the middle 
mouse button. | 


Parameters 


Return Value 


See Also 
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fwKeys | 
Value of wParam. Indicates whether various virtual keys are down. This 
parameter can be any combination of the following values: 


Value Description 
MK_CONTROL Set if CTRL key 1s down. 
MK_LBUTTON Set if left button is down. 


MK_RBUTTON ‘Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


yPos | 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


An application should return zero if it processes this message. 


WM_MBUTTONDBLCLK, WM_MBUTTONDOWN 


WM_MDIACTIVATE nee en 


WM_MDIACTIVATE 

/* Message sent to MDI client */ 

wParam = (WPARAM) (HWND) hwndChildAct; /* child to activate * / 
1Param = @L; /* not used, must be zero */ 


/* Message received by MDI child */ a 
wParam = (WPARAM) fActivate; /* activation flag * / 


hwndAct = (HWND) LOWORD(1Param); /* child being activated § ¥*/ 


hwndDeact = (HWND) HIWORD(1Param) ; /* child being deactivated */ 


An application sends the WM_MDIACTIVATE message to a multiple document 
interface (MDI) client window to instruct the client window to activate a different | 
‘MDI child window. As the client window processes this message, it sends - 
WM_MDIACTIVATE to the child window W Dene deactivated and to the child win- 
dow being activated. 
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Parameters In message sent to MDI client window: 


hwndChildAct 
Value of wParam. Identifies the MDI child window to be activated. 


In message received by MDI child window: 


{Activate 
Value of wParam. Specifies whether to activate or deactivate the child window. 
If this parameter is TRUE, the child window is activated. If this parameter is 
FALSE, the child window is deactivated. 


hwndAct 
Value of the low-order word of /Param. Identifies the child window being 
activated. 

hwndDeact 
Value of the high-order word of /Param. Identifies the child window being 
deactivated. 


Return Value An application should return zero if it processes this message. 


Comments An MDI child window is activated independently of the MDI frame window. 
When the frame window becomes active, the child window that was last activated 
with the WM_MDIACTIVATE message receives the WM_NCACTIVATE mes- 
sage to draw an active window frame and title bar; it does not receive another 
WM_MDIACTIVATE message. 


See Also WM_MDIGETACTIVE, WM_NCACTIVATE, WM_MDINEXT 


WM_MDICASCADE 


~ WM_MDICASCADE 
fnCascade = wParam; /* cascade flag */ 


The WM_MDICASCADE message is sent to a multiple document interface 
(MDI) client window to arrange all its child windows in a cascade format. 


Parameters fnCascade 
Value of wParam. Saari: a cascade flag. Currently, only the following flag 
may be specified: 
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Value Meaning 
~ MDITILE_SKIPDISABLED Prevents disabled MDI child windows from being 
cascaded. 
Return Value An application should return zero if it processes this message. 


See Also WM_MDIICONARRANGE, WM_MDITILE 


WM_MDICREATE 


WM_MDICREATE | 
wParam = Q@; /* not used, must be zero */ 
1Param = (LPARAM) (MDICREATESTRUCT FAR*) lpmcs; /* structure address */ 


An application sends the WM_MDICREATE message to a multiple document in- 
terface (MDI) client window to create a child window. 


Parameters [pmcs 
Value of /Param. Points to an MDICREATESTRUCT structure. The 
MDICREATESTRUCT structure has the following form: 


typedef struct tagMDICREATESTRUCT { /* mdic */ 
-LPCSTR szClass; 
LPCSTR> szTitle; 
HINSTANCE hOwner; 


int x 
int y3 
int CX; 
int Cy; 
DWORD style; 


LPARAM 1Param; 
} MDICREATESTRUCT; 


Return Value _ The return value is the handle of the new window in the low-order word and zero | 
in the igh: order word. a 


Comments | The window is created with the style bits WS_CHILD, ws _CLIPSIBLINGS, 
WS_CLIPCHILDREN, WS_SYSMENU, WS_CAPTION, WS_THICKFRAME, 
WS_MINIMIZEBOX, and WS_MAXIMIZEBOX, plus additional style bits 
specified in the MDICREATESTRUCT structure to which /pmcs points. 
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Windows adds the title of the new child window to the window menu of the frame 
window. An application should create all child windows of the client window with 
this message. 


If the MDIS_-ALLCHILDSTYLES style is set when the MDI client window is 
created, CreateWindow overrides the default style bits. 


If a client window receives any message that changes the activation of child win- 
dows while the currently active MDI child window is maximized, Windows re- 
stores the currently active child window and maximizes the newly activated child 
window. | 


When the MDI child window is created, Windows sends the WM_CREATE mes- 
sage to the window. The /pmcs parameter of the WM_CREATE message contains 
a pointer to a CREATESTRUCT structure. The IpCreateParams member of the 
CREATESTRUCT structure contains a pointer to tte MDICREATESTRUCT 
structure passed with the WM_MDICREATE message that created the MDI child 
window. 


An application should not send a second WM_MDICREATE message while a 
WM_MDICREATE message is still being processed. For example, it should not 


send a WM_MDICREATE message while an MDI child window is processing its 
WM_CREATE message. 


See Also WM_MDIDESTROY 


WM_MDIDESTROY 


WM_MDIDESTROY 
hwndChild = (HWND) wParam; /* handle of child to destroy */ 


An application sends the WM_MDIDESTROY message to a multiple document 
interface (MDI) client window to close an MDI child window. 


Parameters hwndChild 


Value of wParam. Identifies the child window to destroy. 
Return Value An application should return zero if it processes this message. 
Comments This message removes the title of the child window from the frame window and 


deactivates the child window. An application should close all MDI child windows 
with this message. | 
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If a client window receives any message that changes the activation of child win- 
dows while the currently active MDI child window is maximized, Windows re- 
stores the currently active child window and maximizes the newly activated child 
window. 


See Also WM_MDICREATE 


WM_ MDIGETACTIVE : 


WM_MDIGETACTIVE 
The WM_MDIGETACTIVE message retrieves the multiple document interface 


(MDI) child window that is active, along with a flag indicating whether the child 
window is maximized. 


Parameters This message has no parameters. 
Return Value The return value is the handle of the active MDI child window in its low-order 
word. If the window is maximized, the high-order word is 1; otherwise, the high- 


order word is 0. 


See Also WM_MDIACTIVATE 


-WM_MDIICONARRANGE a 


_ WM_MDIICONARRANGE | 

The WM_MDIICONARRANGE message is sent to a multiple document interface — 
(MDI) client window to arrange all minimized document child windows. It does 
not affect child windows that are not minimized. | 

Parameters | This message has no parameters. 


Return Value An application should return zero if it processes this message. 


SeeAlsa = £=£=£8£8£WM_MDICASCADE,WM_MDITILE — 
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WM_MDIMAXIMIZE 


Parameters 


Return Value 


Comments 


WM_MDIMAXIMIZE | 
hwndMaximize = (HWND) wParam; /* handle of child to maximize */ 


The WM_MDIMAXIMIZE message causes a multiple document interface (MDI) 
client window to maximize an MDI child window. When a child window is maxi- 
mized, Windows resizes it to make its client area fill the client window. Windows 
places the child window’s System menu (sometimes referred to as the Control 
menu) in the frame’s menu bar so that the user can restore or minimize the child 
window; Windows adds the title of the child window to the frame window’s menu 
of child windows. 


hwndMaximize 
Value of wParam. Identifies the child window to maximize. 


An application should return zero if it processes this message. 


If an MDI client window receives any message that changes the activation of its 
child windows while the currently active MDI child window is maximized, Win- 
dows restores the currently active child window and maximizes the newly acti- 
vated child window. 


WM_MDINEXT 


Parameters 


_ WM_MDINEXT 
wParam = (WPARAM) hwndChild; /* handle of child window ae / 
}Param = (LPARAM) fNext; /* next or previous child window */ 


An application sends the WM_MDINEXT message to a multiple document inter- 
face (MDI) client window to activate the child window immediately behind the 
currently active child window and place the currently active child window behind 
all other child windows. 


hwndChild 
Value of wParam. Specifies the handle of the child window. 

fNext — | 
Value of /Param. If this parameter is zero, the message specifies that the next 
MDI child window should be activated. If this parameter is nonzero, the mes- 
sage specifies that the previous MDI child window should be activated. 


WM_MDISETMENU ~_—‘'1511 


Return Value An application should return zero if it processes this message. 


Comments If an MDI client window receives any message that changes the activation of its 
child windows while the currently active MDI child window is maximized, Win- 
dows restores the currently active child window and maximizes the newly acti- 
vated child window. 


See Also | ~ WM_MDIACTIVATE, WM_MDIGETACTIVE 


WM_MDIRESTORE 


WM_MDIRESTORE 
wParam = (WPARAM) wIlDChild; /* handle of child window */ | 


An application sends the WM_MDIRESTORE message to a multiple document in- 
terface (MDI) client window to restore an MDI child window from maximized or 
minimized size. 


| Parameters wlDChild 


Value of wParam. Specifies the handle of the child pintlaw. 
Return Value An application should return zero if it processes this message. 
See Also WM_MDIMAXIMIZE 


WM_ MDISETMENU Sas 


~WM_MDISETMENU | 
wParam = (WPARAM) (BOOL) fRefresh;:  /* refresh flag */ 
1Param = MAKELPARAM(hmenuFrame, hmenuWindow); /* new menus ok / 


An application sends a WM_MDISETMENU message to replace the menu of a 
~ multiple document interface (MDI) frame window, the Window pop- up menu, or 
| both. 


Parameters oe fRefresh 
Value of wParam. Specifies whether to refresh the current menus or specify. 
new menus. It is TRUE if the menus should just be refreshed. It is FALSE if, 


152 WM_MDITILE 


instead, the hmenuFrame and hmenuWindow parameters should be used to 
specify new menus for the window. 


hmenuF rame | 
Value of the low-order word of [Param. Identifies the new frame-window 
menu. If this parameter is zero, the frame-window menu is not changed. 


hmenuWindow 
Value of the high-order word of /Param. Identifies the new Window pop-up 
menu. If this parameter is zero, the Window pop-up menu is not changed. 


Return Value The return value is the handle of the frame-window menu replaced by this mes- 
sage. 
Comments After sending this message, an application must call the DrawMenuBar function 


.- to update the menu bar. 


If this message replaces the Window pop-up menu, MDI child-window menu 
items are removed from the previous Window menu and added to the new Win- 
dow pop-up menu. 


If an MDI child window is maximized and this message replaces the MDI frame- 
window menu, the System menu (sometimes referred to as the Control menu) and 
restore controls are removed from the previous frame-window menu and added to 
the new menu. 


See Also DrawMenuBar 


WM_MDITILE a 


WM_MDITILE 
fTile = wParam; /* tiling flag */ 


The WM_MDITILE message is sent to a multiple document interface (MDI) | 
client window to arrange all its child windows in a tiled format. 


Parameters fTile’ 
Value of wParam. Specifies a tiling tag. This parameter can be one of the fol- 
lowing flags: 
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Value Meaning 


MDITILE_HORIZONTAL Tiles MDI child windows so that they are wide 
| rather than tall. | 
MDITILE_SKIPDISABLED _ Prevents disabled MDI child windows from being 
tiled. 
MDITILE_VERTICAL Tiles MDI child windows so that they are tall 
rather than wide. 


Return Value An application should return zero if it processes this message. 


See Also WM_MDICASCADE, WM_MDITCONARRANGE 


WM _MEASUREITEM oe 


WM_MEASUREITEM 
nIDCt] = (int) wParam; oo /* control identifier */ 
TpmisCt] = (MEASUREITEMSTRUCT FAR*) 1Param; /* address of structure */ 


The WM_MEASUREITEM message is sent to the owner of an owner-drawn but- 
ton, combo box, list box, or menu item when the control is created. When the. 
owner receives the message, the owner fills in the MEASUREITEMSTRUCT 
structure pointed to by the /pmisCtl message parameter and returns; this informs | 
Windows of the dimensions of the control. If a list box or combo box 1s created 

- with the LBS_OWNERDRAWVARIABLE or CBS_OWNERDRAWVARIABLE 
style, this message is sent to the owner for each item in the control; otherwise, this 
message is sent once. | 


Parameters nDCtl , 
Value of wParam. Specifies the identifier of the control that sent the 
~WM_MEASUREITEM message. This parameter is 0 if the message was sent 
by a menu. This parameter is —1 when the system is requesting the dimensions 
of an edit control in an owner-drawn combo box. 


[pmisCtl | a 
Value of /Param. Points to a MEASUREITEMSTRUCT structure that con- 
tains the dimensions of the owner-drawn control. 
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Return Value 


| Comments 


See Also 


WM_MENUCHAR 


Parameters 


The MEASUREITEMSTRUCT structure has the following form: 


typedef struct tagMEASUREITEMSTRUCT { /* mi */ 
UINT  CtlType; 
UINT CtlID; 
UINT itemID; 
UINT jtemWidth; 
UINT jitemHeight; 
DWORD itemData; 
} MEASUREITEMSTRUCT; 


An application should return TRUE if it processes this message. 


Windows sends the WM_MEASUREITEM message to the owner of a combo 

box or list box created with the OWNERDRAWFIXED style before sending _ 
WM_INITDIALOG. As a result, when the owner receives this message, Windows 
has not yet determined the height and width of the font used in the control; func- 
tion calls and calculations requiring these values should occur in mee main function 
of the application or library. 


WM_COMPAREITEM, WM_DELETEITEM, WM_DRAWITEM, 
WM_INITDIALOG 


WM_MENUCHAR 


chUser = wParam; | /* ASCII character * / 
fMenu = LOWORD(1Param); /* menu flag x / 
hmenu = (HMENU) HIWORD(1Param) ; /* handle of the menu */ 


The WM_MENUCHAR message is sent when the user presses the key corre- 
sponding to a menu mnemonic character that doesn’t match any of the predefined 
mnemonics in the current menu. It is sent to the window that owns the menu. 


chUser 
Value of wParam. epecEce the ASCII character that corresponds to the eS the 
user pressed. | 


fMenu 


Value of the low-order word of /Param. Specifies the type of the selected 
menu. This parameter can be one of the following values: 
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Value Meaning 


MF_POPUP The menu is a pop-up menu. 


MF _SYSMENU The menu is a System menu (sometimes referred to as a 
Control menu). 


hmenu 
Value of the high-order word of lParam. Identifies the selected menu. 


Return Value The return value is one of the following command code values in the high-order 
word: 
Value Description 
0 Informs Windows that it should discard the character corresponding to the 
key the user pressed, and creates a short beep on the system speaker. 
1 Informs Windows that it should close the current menu. 
2 Informs Windows that the low-order word of the return value contains the 


item number for a specific item. This item is selected by Windows. 


The low-order word is ignored if the high-order word contains 0 or 1. An applica- 
tion should process this message when an accelerator key has been used to select a 
bitmap placed in a menu. | 


Comments The WM_MENUCHAR message is generated when the user presses ALT and any 
| key, even if the key does not correspond to a mnemonic character. In this case, the © 
hmenu parameter contains the window handle of the menu. 


(Co ¢ 


WM_MENUSELECT ae a] 


WM_MENUSELECT 


wIDItem = wParan; /* item identifier or menu handle */ 
fwMenu = LOWORD(1Param); /* menu flags * / 
hmenu = (HMENU) HIWORD(1Param); /* handle of the menu * / 


The WM_MENUSELECT message is sent to the window associated with a menu 
when the user selects a menu item. 


Parameters wlDItem | 
| Value of wParam. Specifies the menu-item identifier if the selected item is a 
menu item. If the selected item contains a pop-up menu, w/D/tem contains the 
handle of the pop-up menu. 
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fwMenu | | 
Low word of /Param. Specifies one or more menu flags. This parameter can be 
a combination of the following values: 


- Flag Description 
MF_BITMAP Item is a bitmap. 
MF_CHECKED Item is checked. 
MF_DISABLED Item is disabled. 
MF_GRAYED | Item is grayed. 


MF_MOUSESELECT Item was selected with a mouse. 
MF_OWNERDRAW Item is an owner-drawn item. 


MF_POPUP Item contains a pop-up menu. 
MF_SEPARATOR Item is a menu-item separator. 
MF_SYSMENU Item is contained in the System menu (sometimes re- 


ferred to as the Control menu). The Amenu parameter 
identifies the System menu associated with the message. 


hmenu 
High word of /Param. If the fwMenu parameter contains the MF_SYSMENU 
flag, this parameter specifies the menu handle of the System menu. 


Return Value An application should return zero if it processes this message. 


Comments If the fwMenu parameter contains —1 and the hmenu parameter contains 0, Win- 
dows has closed the menu. This occurs both when the menu is closed because the 
user pressed ESC or clicked outside the menu and when the user has selected a 
menu item. 


WM_MOUSEACTIVATE fics 


WM_MOUSEACTIVATE | 
hwndTopLevel = (HWND) wParam; /* handle of top-level parent */ 
_ WHitTestCode = LOWORD(1Param); /* hit-test code | * / 
wMsg = HIWORD(1Param); /* mouse-message identifier * / 


The WM_MOUSEACTIVATE message is sent when the cursor is in an inactive 
window and the user presses a mouse button. The parent window receives this 
message only if the child window passes it to the DefWindowProc function. 
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Parameters hwndTopLevel 
Value of wParam. Identifies the io -level parent window of the window being 
activated. 


wHitTestCode 


Value of the low-order word of /Param. Specifies the hit-test area a code. A hit 
test is a test that determines the location of the cursor. 


wMsg 
Value of the high-order word of /Param. Specifies the identifier of the mouse 
message. 


Return Value The return value specifies whether the window should be activated and whether 
the mouse event should be discarded. It must be one of the following values: 


Value Meaning 
MA_ACTIVATE Activate the window. 
MA_NOACTIVATE Do not activate the window. | 
MA_ACTIVATEANDEAT Activate the window and discard the mouse event. 
MA_NOACTIVATEANDEAT Do not activate the window; discard the mouse 
event. 
~ Comments If the child window passes the message to the Def WindowProc function, Def- 


WindowProc passes this message to a window’s parent window before any pro- 
cessing occurs. If the parent window returns a nonzero value, processing is halted. 


WM_MOUSEMOVE tn 


WM_MOUSEMOVE 


fwkeys = wParam; /* key flags * / 
xPos = LOWORD(1Param); /* horizontal position of cursor */ 
yPos = HIWORD(1Param) ; /* vertical position of cursor #*/ 


The WM_MOUSEMOVE message is sent to a window when the mouse cursor — 
moves. If the mouse is not captured, the message goes to the window beneath the 
cursor. Otherwise, the message goes to the window that has captured the mouse. 


Parameters jfwKeys 
| Value of wParam. Indicates whether various virtual keys are down. This 
parameter can be any combination of the following values: 
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Return Value 


Comments 


See Also 


WM_MOVE 


Parameters 


Value Description 


MK_CONTROL Set if CTRL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON Set if middle button is down. 
MK RBUTTON _ Setif right button is down. 
MK_SHIFT Set if SHIFT key is down. 


xPos | 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor, aS a screen coordinate. 


yPos — 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor, as a screen coordinate. 

An application should return zero if it processes this message. 


The MAKEPOINT macro can be used to convert the /Param parameter to a 
POINT structure. 


SetCapture, WM_NCHITTEST 


WM_MOVE a 
xPos = (int) LOWORD(1Param) ; /* horizontal position */ 
yPos = (int) HIWORD(1Param) ; /* vertical position * / 


The WM_MOVE message is sent after a window has been moved. 


xPos — 
Value of the low-order werd of lParam. Specifies the new x- ecard mate of the 
_ upper-left corner t of the client area of the window. 


yPos 
Value of the high- -order word of /Param. Specifies the new ry- -coordinate of the 
upper-left corner of the client area of the window. 
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Return Value An application should return zero if it processes this message. 


Comments The xPos and yPos parameters are given in screen coordinates for overlapped and 
7 pop-up windows and in parent-client coordinates for child windows. 


An application can use the MAKEPOINT macro to convert the /Param parameter 
to a POINT data structure. 


See Also MAKEPOINT, POINT 


WM_NCACTIVATE a 


WM_NCACTIVATE 
fActive = (BOOL) wParam; /* the active/inactive flag */ 


The WM_NCACTIVATE message is sent to a window when its nonclient area 
needs to be changed to indicate an active or inactive state. 


Parameters fActive | 
Value of wParam. Specifies when a title bar or icon needs to be changed to indi- 
cate an active or inactive state. The fActive parameter is TRUE if an active title 
bar or icon is to be drawn. It is FALSE for an inactive title bar or icon. 


Return Value When the fActive parameter is FALSE, an application should return TRUE to indi- 
cate that Windows should proceed with the default processing or FALSE to pre- 
vent the caption bar or icon from being deactivated. When /Active is TRUE, the 
return value is ignored. | | 


Comments — The DefWindowProc function draws the title bar and title bar text in their active 
colors when the fActive parameter is TRUE and in their inactive colors when 
fActive is FALSE. | 


See Also -DefWindowProc 
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WM_NCCALCSIZE | [2x | 


WM_NCCALCSIZE | 
fCalcValidRects = (BOOL) wParam; /* valid-area flag */ 
Ipncsp = (NCCALCSIZE_PARAMS FAR*) 1Param; /* address of data */ 


The WM_NCCALCSIZE message is sent when the size and position of a win- 
dow’s client area needs to be calculated. By processing this message, an applica- 
tion can control the contents of the window’s client area when the size or position 
of the window changes. 


Parameters fCalcValidRects 
Value of wParam. Specifies whether the application should specify which part 
of the client area contains valid information. Windows will copy the valid infor- 
mation to the specified area within the new client area. If this parameter is 
TRUE, the application should specify which part of the client area is valid. 


[pncsp | 
Value of lParam. Points to an NCCALCSIZE_PARAMS data structure that 
contains information an application can use to calculate the new size and posi- - 
tion of the client rectangle. The NCCALCSIZE_PARAMS structure has the 
following form: 


typedef struct tagNCCALCSIZE_PARAMS { 
RECT rgrcl3]; 

| WINDOWPOS FAR* lIppos; 

} NCCALCSIZE_PARAMS; 


Regardless of the value of fCalcValidRects, the first rectangle in the array 

specified by the rgre member contains the coordinates of the window. For a 

child window, the coordinates are relative to the parent window’s client area. 

For top-level windows, the coordinates are screen coordinates. An application 

should process WM_NCCALCSIZE by modifying the rgre[0] rectangle to re- 
__ flect the size and position of the client area. 


The rerc[1] and rgrc[2] rectangles are valid only if fCalcValidRects is TRUE. 
In this case, the rgre[1] rectangle contains the coordinates of the window 
before it was moved or resized. The rgre[2] rectangle contains the coordinates 
of the window’s client area before the window was moved. All coordinates are 
relative to the parent window or screen. 


Return Value An application should return zero if fCalcValidRects is FALSE. 


An application can return zero or a valid combination of the following values if 
fCalcValidRects is TRUE: 


Comments 


See Also 


Value 


WVR_ALIGNTOP, WVR_ALIGNLEFT, 


WVR_ALIGNBOTTOM, 
WVR_ALIGNRIGHT 


WVR_HREDRAW, 
WVR_VREDRAW 


WVR_REDRAW 


~ WVR_VALIDRECTS 
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Meaning 


These values, used in combination, 

specify that the client area of the window 
is to be preserved and aligned appro- 
priately relative to the new location of the 
client window. For example, to align the 
client area to the lower-left, return | 
WVR_ALIGNLEFT | WVR_ALIGNTOP. 


These values, used in combination with 
any other values, cause the window to be 
completely redrawn if the client rectangle 
changed size horizontally or vertically. 
These values are similar to the 
CS_HREDRAW and CS_VREDRAW 


class styles. 


This value causes the entire window 
to be redrawn. It is a combination - 
of WVR_HREDRAW and 
WVR_VREDRAW. 


This value indicates that, upon return from 
WM_NCCALCSIZE, the rgre[1] and — 
rgre[2] rectangles contain valid source 
and destination area rectangles, respec- 
tively. Windows combines these rectan- — 
gles to calculate the area of the window 
that can be preserved. Windows copies 
any part of the window image that is _ 
within the source rectangle and clips the — 
image to the destination rectangle. Both 
rectangles are in parent-relative or screen- 
relative coordinates. 


This return value allows an application to - 
implement more elaborate client-area pre- 
servation strategies, such as centering or 
preserving a subset of the client area. 


If fCalcValidRects is TRUE and an application returns zero, the old client area is 
preserved and is aligned with the upper-left corner of the new client area. 


Redrawing of the window may occur, depending on whether CS_HREDRAW or 
CS_VREDRAW was specified. This is the default, backward-compatible Def- 
WindowProc processing of this message (in addition to the usual client rectangle 


~ calculation described in the preceding table). 


-DefWindowProc, MoveWindow, SetWindowPos | 
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WM_NCCREATE —. es 


WM_NCCREATE 
Tpcs = (CREATESTRUCT FAR*) 1Param; /* address of initialization data */ 


The WM_NCCREATE message is sent prior to the WM_CREATE message when 
a window is first created. 


Parameters Ipcs 


Value of /Param. Points to the CREATESTRUCT data structure for the win- 
dow. The CREATESTRUCT structure has the following form: 


typedef struct tagCREATESTRUCT { £=*/* cs */ 
void FAR* 1pCreateParams ; 
HINSTANCE hInstance; 


HMENU hMenu; 

HWND hwndParent; 
int Cy; 

int i “ORS 

int y3 

int x: 

LONG style; 


LPCSTR lpszName; 

LPCSTR lpszClass; 

DWORD dwExStyle; 
} CREATESTRUCT; 


Return Value The return value is nonzero if the nonclient area is created. It is zero if an error 
occurs; in this case, the CreateWindow or CreateWindowEx function will return 
NULL. 


Comments Scroll bars are initialized (the scroll bar position and range are set), and the win- 
dow text is set. Memory used internally to create and maintain the window is allo- 
cated. 


See Also CreateWindow, WM_CREATE 
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WM_NCDESTROY ea 


WM_NCDESTROY 


The WM_NCDESTROY message informs a window that its nonclient area is 
being destroyed. The Destroy Window function sends the WM_NCDESTROY 
message to the window following the WM_DESTROY message. 
WM_NCDESTROY is used to free the allocated memory oa associated with 


the window. 
Parameters This message has no parameters. 
Return Value An application should return zero if it processes this message. 
Comments This message fees any memory internally allocated for the window. 


See Also -- DestroyWindow, WM_NCCREATE 


WM NCHITTEST ae ee (ax 


WM_NCHITTEST 7 | | 
xPos = (int) LOWORD(1 Param) ; /* horizontal position of cursor */ 
yPos = (int) HIWORD(1Param) ; /* vertical position of cursor = */ 


The WM_NCHITTEST message is sent to the window that contains the cursor or 
_to the window that used the SetCapture function to capture the mouse input. It is 
sent every time the mouse is moved. | 


Parameters xPos 
: Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor, in screen coordinates. | 


yPos | 
Value of the high-order word of lParam. Specifies the y-coordinate of the cur- 
sor, in screen coordinates. | 


Return Value The return value of the DefWindowProc function is one of the following values 
_ Indicating the position of the cursor: 
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Comments 


Example 


Value 
HTBORDER 


HTBOTTOM 
HTBOTTOMLEFT 


HTBOTTOMRIGHT 


HTCAPTION 
HTCLIENT 
HTERROR 


HTGROWBOX 
HTHSCROLL 
HTLEFT 
HTMAXBUTTON 
HTMENU 
HTMINBUTTON 
HTNOWHERE 


HTREDUCE 
HTRIGHT 
HTSIZE 

HTS YSMENU 


HTTOP 
HTTOPLEFT 
HTTOPRIGHT 


HTTRANSPARENT 


HTVSCROLL 
HTZOOM 


Meaning 


In the border of a window that does not have a sizing border 
In the lower horizontal border of a window 

In the lower-left corner of a window border 

In the lower-right corner of a window border 

In a title bar area 

In a client area 


On the screen background or on a dividing line between win- 
dows (same as HTNOWHERE except that the DefWindow- 
Proc function produces a system beep to indicate an error) 


In a size box (same as HTSIZE) 
In the horizontal scroll bar 

In the left border of a window 
In a Maximize button 

In a menu area 

In a Minimize button 


On the screen background or on a dividing line between 
windows 


In a Minimize button 
In the right border of a window 
In a size box (same as HTGROWBOX) 


In a System menu (sometimes referred to as a Control menu) 
or in a close button in a child window 


In the upper horizontal border of a window 
In the upper-left corner of a window border 


_ In the upper-right corner of a window border 


In a window currently covered by another window 
In the vertical scroll bar 
In a Maximize button . ) 


The MAKEPOINT macro can be used to convert the [Param parameter to a 


POINT structure. 


This example shows a portion of a subclass procedure that detects mouse mes- 
Sages in a static window: 


See Also 


WM_ NCLBUTTONDBLCLK 


Parameters 


Return Value 
Comments 


— See Also 
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LONG 1RetVal; 

case WM_NCHITTEST: ; 
1RetVal = DefWindowProc(hwnd, msg, wParam, |Param); 
if (1]RetVal == HTTRANSPARENT) { 


. /* Process mouse events in static window. */ 


4S 
break; 


default: 


CallWindowProc(1pStaticProc, hwnd, msg, wParam, 1Param); 


DefWindowProc, GetCapture 


WM_ NCLBUTTONDBLCLK | . 
nHittest = wParam; /* hit-test code * / 
xCursor = LOWORD(1Param) ; /* cursor horizontal. position */ 

yCursor = HIWORD(1Param); /* cursor vertical position */ 

The WM_NCLBUTTONDBLCLK message is sent when the user double-clicks _ 
the left mouse button while the cursor is within a nonclient area of the window. 


nHittest 
Value of wParam. Specifies the code returned by WM_NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. 


~ xCursor 


Value of the low-order word of /Param. Specifies the horizontal position of the 
cursor, in screen coordinates. | oS 


yCursor 


Value of the high-order word of /Param. Specifies the vertical position of the 
cursor, in screen coordinates. 


An application should return zero if it processes this message. 


If appropriate, WM_SYSCOMMAND messages are sent. _ 


-WM_NCHITTEST, WM_SYSCOMMAND 
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WM_NCLBUTTONDOWN Ba 


WM_NCLBUTTONDOWN 


wHitTestCode = wParam; /* hit-test code *&/ 
xPos = LOWORD(1Param) ; /* horizontal cursor position */ 
yPos = HIWORD(1Param) ; /* vertical cursor position ¥*/ 


The WM_NCLBUTTONDOWN message is sent to a window when the user 
presses the left mouse button while the cursor is within a nonclient area of the win- 
dow. 


Parameters wHitTestCode 
Value of wParam. Specifies the code returned by WM_NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor, in screen coordinates. 


yPos 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
Sor, in screen coordinates. | 


Return Value An application should return zero if it processes this message. 
Comments If appropriate, WM_SYSCOMMAN D messages are sent. 
See Also | WM_NCHITTEST, WM_NCLBUTTONDBLCLK, WM_NCLBUTTONUP, 


WM_SYSCOMMAND 


WM_NCLBUTTONUP ers 


‘WM_NCLBUTTONUP : 
wHitTestCode = wParam; /* hit-test code * / 


xPos = LOWORD(1Param); /* horizontal cursor position */ 
yPos = HIWORD(1Param); /* vertical cursor position ¥*/ 


The WM_NCLBUTTONUP message is sent to a window when the user releases 
the left mouse button while the cursor is within a nonclient area of the window. 


Parameters wHitTestCode | | | 
| Value of wParam. Specifies the code returned by WM_NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. 


Return Value 
Comments 


See Also 


WM_NCMBUTTONDBLCLK | 


Parameters 


Return Value 


See Also 
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xPos 
~ Value of the low-order word of /Param. Specifies the X- coordinate of the cur- 
sor, in screen coordinates. _ 


yPos 
Value of the high-order word of /Param. Specifies the y- -coordinate os the cur- — 
sor, in screen coordinates. 


An application should return zero if it processes this message. 
If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCHITTEST, WM_ NCLBUTTONDOWN, WM_ _NCLBUTTONUP, 


_WM_SYSCOMMAND 


WM_NCMBUTTONDBLCLK 
wHitTestCode = wParam; /* hit-test code. x / 


xPos = LOWORD(1Param);  /* horizontal cursor position */. 
yPos = HIWORDC| Param). /* vertical cursor pos eye) */ 


The WM _NCRBUTTONDOWN message is sent toa window when the user 
double-clicks the middle mouse button while the cursor is within a nonchent : area 


of the window. | 


wHitTestCode 


Value of wParam. Specifies the code returned by WM _NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. 


xPos 
Value of the low-order word of [Param. Specifies the x- -coordinate of the cur- 
sor, as a Screen coordinate. 8 | 


yPos : | 
Value of the high-order word of Param. Specifies the y-coordinate of the cur- 
_ Sor, as a screen coordinate. © 


An application should retain zero if it processes this message. | 


-WM_NCHITTEST, WM_NCMBUTTONDOWN, WM_NCMBUTTONUP 
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WM_NCMBUTTONDOWN [2x] 


Parameters 


Return Value 


See Also 


WM_ NCMBUTTONDOWN 


_wHitTestCode = wParam; /* hit-test code a / 
xPos = LOWORD(1Param) ; /* horizontal cursor position */ 
yPos = HIWORD(1Param) ; /* vertical cursor position */ 


The WM_NCMBUTTONDOWN message is sent to a window when the user 
presses the middle mouse button while the cursor is within a nonclient area of the 
window. 


wHitTestCode 
Value of wParam. Specifies the code returned by WM_NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. _ 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
Sor, as a Screen coordinate. 


yPos 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor, as a screen coordinate. 

An application should return zero if it processes this message. 


WM_NCHITTEST, WM_NCMBUTTON DBLCLK, WM_NCMBUTTONUP 


WM_NCMBUTTONUP Bx 


Parameters 


WM_NCMBUTTONUP 


wHitTestCode = wParam; /* hit-test code * / 
xPos = LOWORD(1Param); /* horizontal cursor position */ 
yPos = HIWORD(1Param) ; /* vertical cursor position * / 


The WM_NCMBUTTONUP message is sent to a window when the user releases 
the left mouse button while the cursor is within a nonclient area of the window. 


wHitlestCode 
Value of wParam. Specifies the code returned by WM _NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
Sor, as a screen coordinate. 


Return Value 


See Also 
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yPos | | 
Value of the high-order word of [Param. Specifies the y-coordinate of the cur- 
Sor, aS a Screen coordinate. 

An application should return zero if it processes this message. 


WM_NCHITTEST, WM_NCMBUTTONDBLCLK, WM_NCMBUTTONDOWN 


WM_NCMOUSEMOVE = tS ray 


Parameters 


Return Value 
Comments 


See Also 


WM_NCMOUSEMOVE 


wHitTestCode = wParam; /* hit-test code * / 
xPos = LOWORD(1Param); /* horizontal cursor position */ 
yPos = HIWORD(1Param) ; /* vertical cursor position a / 


The WM_NCMOUSEMOVE message is sent to a window when the cursor is 
moved within a nonclient area of the window. 


_ wHitTestCode 


Value of wParam. Specifies the code returned by WM _NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor, aS a Screen coordinate. 


yPos 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor, aS a Screen coordinate. 

An application should return zero if it processes this message. 


If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCHITTEST, WM_SYSCOMMAND 
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WM NCPAINT ax 


WM_NCPAINT 


The WM_NCPAINT message is sent to a window when its frame needs painting. 


Parameters This message has no parameters. 
Return Value _ An application should return zero if it processes this message. 
Comments. The DefWindowProc function paints the window frame. 


An application can intercept this message and paint its own custom window frame. 
The clipping region for a window is always rectangular, even if the shape of the 
frame is altered. 


See Also DefWindowProc 
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WM_ NCRBUTTONDBLCLK 


wHitTestCode = wParam; /* hit-test code * / 
xPos = LOWORD(1Param) ; /* horizontal cursor position */ 
yPos = HIWORD(1Param): /* vertical cursor position  */ 


The WM_NCRBUTTONDBLCLK message is sent to a window when the user © 
double-clicks the right mouse button while the cursor is within a nonclient area of 
the window. 


Parameters wHitTestCode 
Value of wParam. Specifies the code returned by WM_NCHITTEST. For more 
information, see the Se of the WM_NCHITTEST message. 


xPos 7 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor, as a screen coordinate. | 


yPos | 
Value of the high-order word of [Param. Specifies the y-coordinate of the cur- 
sor, aS a Screen coordinate. 


Return Value 


See Also 


WM_NCRBUTTONDOWN 


Parameters 


Return Value 


See Also 


WM_NCRBUTTONDOWN 171 


An application should return zero if it processes this message. 


WM_NCHITTEST, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP 


WM_NCRBUTTONDOWN 


wHitTestCode = wParam; | /* hit-test code a / 
xPos = LOWORD(1Param) ; /* horizontal cursor position */ 
yPos = HIWORD(1Param); /* vertical cursor position * / 


The WM_NCRBUTTONDOWN message is sent to a window when the user 
presses the right mouse button while the cursor is within a nonclient area of the 
window. 


wHitTestCode 
Value of wParam. Specifies the code returned by WM_NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. 


xPos 
Value of the low-order word of /Param. Specifies the x- coordinate of the cur- 
sor, aS a Screen coordinate. 


yPos 
Value of the high-order word of /Param. Specifies the y- edscediniate of the cur- 
Sor, aS a Screen coordinate. . 

An application should return zero if it processes this message. 


WM_NCHITTEST, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONUP 
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WM_NCRBUTTONUP a ad 


WM_NCRBUTTONUP 


wHitTestCode = wParam; /* hit-test code * / 
xPos = LOWORD(1Param) ; /* horizontal cursor position */ 
yPos = HIWORD(1Param) ; /* vertical cursor position * / 


The WM_NCRBUTTONUP message is sent to a window when the user releases 
the right mouse button while the cursor is within a nonclient area of the window. 


Parameters wHitTestCode | | 
Value of wParam. Specifies the code returned by WM_NCHITTEST. For more 
information, see the description of the WM_NCHITTEST message. 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor, aS a Screen coordinate. 


yPos : 
Value of the high-order word of lParam. Specifies the y-coordinate of the cur- 
Sor, aS a Screen coordinate. 


Return Value An application should return zero if it processes this message. 


See Also WM_NCHITTEST, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN 


WM_NEXTDLGCTL ax] 


WM_NEXTDLGCTL | 
wCt|lFocus = wParam; /* jdentifies control for focus */ 
fHandle = (BOOL) LOWORD(1Param); /* wParam handle flag * / 


An application sends the WM_NEXTDLGCTL message to a dialog box procedure 
to set the focus to a different control in a dialog box. 


Parameters wCilFocus 7 | 
Value of wParam. If the fHandle parameter is nonzero, the wCtlFocus parame- 
ter is the handle of the control that receives the focus. If fHandle is zero, 
wCtlFocus is a flag that indicates whether the next or previous control with the 
WS_TABSTOP style receives the focus. If wCtlFocus is zero, the next control 
receives the focus; otherwise, the previous control with the WS_TABSTOP 
_ Style receives the focus. 
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fHandle 
Low-order word of /Param. Indicates how Windows uses the wParam parame- 
ter. If fHandle is nonzero, wParam is a handle associated with the control that 
receives the focus; otherwise, wParam is a flag that indicates whether the next 
or previous control with the WS_TABSTOP style receives the focus. 


Return Value An application should return zero if it processes this message. 


Comments The effect of this message differs from that of the SetFocus function because 
WM_NEXTDLGCTL modifies the border around the default button. 


Do not use the SendMessage function to send a WM_NEXTDLGCTL message if 
your application will concurrently process other messages that set the control 
focus. In this case, use the PostMessage function instead. 


See Also PostMessage, SendMessage, SetFocus 


WM_PAINT he aexa 


The WM_PAINT message is sent when Windows or an application makes a re- 
quest to repaint a portion of an application’s window. The message is sent when 
the UpdateWindow or Redraw Window function is called or by the Dispatch- | 
Message function when the application obtains a WM_PAINT message by using 
the GetMessage or PeekMessage function. 


Parameters This message has no parameters. 
Return Value An application should return zero if it processes this message. 
Comments The DispatchMessage function sends this message when there are no other mes- — 


Sages in the application’s message queue. © 


A window may receive internal paint messages as a result of calling the Redraw- 
Window function with the RDW_INTERNALPAINT flag set. In this case, the 
window may not have an update region. An application should call the Get- 
UpdateRect function to determine whether the window has an update region. If 
GetUpdateRect returns zero, the application should not call the BeginPaint and 
EndPaint functions. 
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See Also 


WM_PAINTCLIPBOARD 


Parameters 


It is an application’s responsibility to check for any necessary internal repainting 
or updating by looking at its internal data structures for each WM_PAINT mes- 
sage, because a WM_PAINT message may have been caused by both an invalid 
area and a call to the RedrawWindow function with the 
RDW_INTERNALPAINT flag set. 


An internal WM_PAINT message is sent only once by Windows. After an internal 
WM_PAINT message is returned from the GetMessage or PeekMessage function 
or is sent to a window by the Update Window function, no further WM_PAINT 
messages will be sent or posted until the window is invalidated or until the 
RedrawWindow function is called again with the RDW_INTERNALPAINT flag 
set. 


BeginPaint, DispatchMessage, EndPaint, GetMessage, PeekMessage, Redraw- 
Window, UpdateWindow 


WM_PAINTCLIPBOARD 


~ hwndViewer = (HWND) wParam; /* handle of viewer * / 


pps = (PAINTSTRUCT FAR*) LOWORD(1Param); /* points to paint data */ 


The WM_PAINTCLIPBOARD message is sent by a clipboard viewer to the 
clipboard owner when the owner has placed data on the clipboard in the 
CF_OWNERDISPLAY format and the clipboard viewer’s client area needs 
repainting. 


hwndViewer 
Value of wParam. Specifies a handle to the clipboard viewer window. 


pps | 
Value of the low-order word of lParam. Points to a PAINTSTRUCT data 
structure that defines which part of the client area to paint. The PAINT- 
STRUCT structure has the following form: 


typedef struct tagPAINTSTRUCT { /* ps */ 
~HDC hdc; . 
 BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[16]; 
} PAINTSTRUCT; 
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Return Value An application should return zero if it processes this message. 


Comments To determine whether the entire client area or just a portion of it needs repainting, 
the clipboard owner must compare the dimensions of the drawing area given in the 
rcPaint member of the PAINTSTRUCT structure to the dimensions given in the 
most recent WM_SIZECLIPBOARD message. 


An application must use the GlobalLock function to lock the memory that con- 
tains the PAINTSTRUCT data structure. The application should unlock that 
memory by using the GlobalUnlock function before it yields or returns control. 


See Also GlobalLock, GlobalUnlock, WM_SIZECLIPBOARD 


WM_PALETTECHANGED 


WM_ PALETTECHANGED 
hwndPalChg = (HWND) wParam; /* handle of window that changed palette */ 


~The WM_PALETTECHANGED message is sent to all top-level and overlapped 
windows after the window with the input focus has realized its logical palette, 
thereby changing the system palette. This message allows a window without the 
input focus that uses a color palette to realize its logical palette and update its 
client area. 


Parameters hwndPalChg 
Value of wParam. Specifies the handle of the window that caused the system 
palette to change. 


Return Value An application should return zero if it processes this message. 


Comments This message is sent to all top-level and overlapped windows, including the one 
that changed the system palette and caused this message to be sent. If any child 
windows use a color palette, this message must be passed on to them. 


~ To avoid an infinite loop, a window that receives this message should not realize 
its palette unless it determines that wParam does not contain its own window 
handle. 
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Example This example shows how an application selects and realizes its logical palette: 


HDC hdc; 
HPALETTE hpalApp, hpalT; 
UINT i; 


/* 
* If this application changed the palette, ignore the message. 
* / 


case WM_PALETTECHANGED: 
if (wParam == hwnd) 
return @L; 
/* Otherwise, fall through to WM_QUERYNEWPALETTE. */ 
case WM_QUERYNEWPALETTE: 
/* 


* If realizing the palette causes the palette to change, 
* redraw completely. 


* / 
hdc = GetDC(hwnd); | 
hpalT = SelectPalette (hdc, hpalApp, FALSE); 


ij = RealizePalette(hdc); /* i == entries that changed */ 
SelectPalette (hdc, hpalT, FALSE); 

ReleaseDC(hwnd, hdc); 

/* If any palette entries changed, repaint the window. */ 


if (i > @) 
InvalidateRect(hwnd, NULL, TRUE); 


return i; 


‘See Also _ WM_PALETTEISCHANGING, WM_QUERYNEWPALETTE 
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WM_PALETTEISCHANGING xa 


WM_PALETTEISCHANGING | 
panaeeal ee = (HWND) wParam; /* handle of window to realize palette 2 / 


The WM _PALETTEISCHANGING message informs applications that an applica- 
tion 1s going to realize its logical palette. 


Parameters hwndRealize : 
Value of wParam. Specifies the handle of the window that is going to realize its 
logical palette. 

Return Value An application should return zero if it processes this message. 

See Also WM_PALETTECHANGED, WM_QUERYNEWPALETTE 


WM_PARENTNOTIFY Sg 


WM_ PARENTNOTIFY 


fwEvent = wParam; /* event flags | */ 
wValuel = LOWORD(1Param); /* child handle/cursor x-coordinate */ 
wValue2 = HIWORD(1Param); /* child ID/cursor y-coordinate * / 


The WM_PARENTNOTIFY message is sent to the parent of a child window 
when the child window is created or destroyed or when the user clicks a mouse 
button while the cursor is over the child window. When the child window is being 
created, the system sends WM_PARENTNOTIFY just before the CreateWindow 
or CreateWindowEx function that creates the window returns. When the child 
window is being destroyed, the system sends the message before any processing to. 
destroy the window takes Ea Pee or 5 


Parameters fwEvent 
| Value of wParam. Specifies the event for which the parent 1S being notified. It 
_can be any of the following values: 


Value Description Pine 
WM_CREATE oe The child window is being created. — 
- WM_DESTROY | _ The child window is being destroyed. 


WM_LBUTTONDOWN The user has placed the mouse cursor over the child | 
: window and clicked the left mouse button. 
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Return Value 


Comments 


See Also 


WM PASTE 


Value Description 


WM_MBUTTONDOWN The user has placed the mouse cursor over the child 
window and clicked the middle mouse button. 

WM_RBUTTONDOWN The user has placed the mouse cursor over the child 
window and clicked the right mouse button. 


wValuel 
Value of the low-order word of /Param. If the fwEvent parameter is 
_ WM_CREATE or WM_DESTROY, the wValue/ parameter specifies the 
_ handle of the child window. Otherwise, wValue1 specifies the x-coordinate of 
the cursor. 


wValue2 
Value of the high-order word of /Param. If fwEventis WM_CREATE or 
WM_DESTROY, the wValue2 parameter specifies the identifier of the child 
window. Otherwise, wValue2 specifies the y-coordinate of the cursor. 


An application should return zero if it processes this message. 


This message is also sent to all ancestor windows of the child window, including 
the top-level window. 


All child windows except those that have the WS_EX_NOPARENTNOTIFY send 
this message to their parent windows. By default, child windows in a dialog box 
have the WS_EX_NOPARENTNOTIFPY style unless the CreateWindowEx func- 
tion was called to create the child window without this style. 


CreateWindow, CreateWindowEx, WM_CREATE, WM_DESTROY, | 


~ WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_RBUTTONDOWN 


[ 2x | 


WM_ PASTE 
wParam = Q; /* not used, must be zero */ 
1Param = @L; /* not used, must be zero */ 


An application sends the WM_PASTE message to an edit control or combo box to 
insert the data from the clipboard into the edit control at the current cursor posi- 
tion. Data is inserted only if the clipboard contains data in CF_TEXT format. 
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Parameters | This message has no parameters. 

Return Value = —‘ The return value is nonzero if this message is sent to an edit control or a combo 
box. 

Example This example pastes data from the clipboard to an edit control: 


SendDigItemMessage(hdlg, IDD_MYEDITCONTROL, WM_PASTE, @, QL); 


See Also -WM_CLEAR, WM_COPY, WM_CUT 


WM POWER oc se pan] 


WM_ POWER | Bees Gey 
fwPowerEvt = wParam; /* power-event notification message */ 


The WM_POWER message is sent when the system, typically a battery-powered 
personal computer, is about to enter the suspended mode. 


Parameters fwPowerEvt _ | 
7" Value of wParam. Specifies a power-event notification message. This parame- 
ter may be one of the following values: . 


Value . Meaning 
PWR_SUSPENDREQUEST Indicates that the system is about to enter the sus- 
| pended mode. 


PWR_SUSPENDRESUME Indicates that the system is resuming operation 
after entering the suspended mode normally—that | 
is, the system sent a PWR_SUSPENDREQUEST 
notification message to the application before the 
system was suspended. An application should per- 
form any necessary recovery actions. 

PWR_CRITICALRESUME Indicates that the system is resuming operation 
after entering the suspended mode without first 
sending a PWR_SUSPENDREQUEST notifica- 
tion message to the application. An application 
should perform any necessary y Tpeovery actions. 


Return Value —S- The value an application should return depends on the value of the wParam para- 
. meter, as follows: 
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Comments 


See Also 


Value of wParam Return Value 


PWR_SUSPENDREQUEST PWR_FAIL to prevent the system from entering the 
: suspended state; otherwise PWR_OK 


PWR_SUSPENDRESUME 0 
PWR_CRITICALRESUME 0 


This message is sent only to an application that is running on a system that con- 
forms to the advanced power management (APM) basic input-and-output system 
(BIOS) specification. The message is sent by the power-management driver to _ 
each window returmed by the Enum Windows function. 


The suspended mode is the state in which the greatest amount of power savings 
occurs, but all operational data and parameters are preserved. Random-access 
memory (RAM) contents are preserved, but many devices are likely to be turned 
off. | - 


EnumWindows 


WM_ QUERYDRAGICON 


Parameters 


Return Value 


Comments 


WM_QUERYDRAGICON 


The WM_QUERYDRAGICON message is sent to a minimized (iconic) window 
that does not have an icon defined for its class. The system sends this message 
whenever it needs to display an icon for the window. 


This message has no parameters. 


An application should return a doubleword value that contains a cursor or icon 
handle in the low-order word. The cursor or icon must be compatible with the dis- 
play driver’s resolution. If the application returns NULL, the system displays the 
default cursor. The default return value is NULL. 


If an application returns the handle of an icon or cursor, the system converts the 
icon or cursor to black-and-white. 


The application can call the LoadCursor or LoadIcon function to load a cursor or 
icon from the resources in its executable file and to obtain this handle. 


WM_QUERYENDSESSION 181 


~ Example This example returns an icon handle in response to the WM_QUERYDRAGICON 
message. The icon is loaded from the resources in the application’s executable file. 


static HICON hIcon; 


switch(msg) { 
~ case WM_CREATE: 


/* Load icon resource. */ 
hIcon = LoadIcon(hInstance, (LPCSTR) “MyIcon"); 


. /* Initialize other variables. */ 


return @L; 
case WM QUERYDRAGICON: 


/* Icon is about to be dragged. Return handle to custom icon. */ 


return (hicon); 
. /* Process other messages. */ 


} 


See Also —....... LoadCursor, LoadIcon 


WM_QUERYENDSESSION = [ax] 


WM_QUERYENDSESSION 


The WM_QUERYENDSESSION message is sent when the user chooses to end 
the Windows session, or when an application calls the ExitWindows function. If _ 
any application returns zero, the Windows session is not ended. Windows stops _ 
sending WM_QUERYENDSESSION messages as soon as one application returns 

_ zero and sends WM_ENDSESSION messages, with the wParam parameter set to 
FALSE, to any applications that have already returned nonzero. 
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Parameters 


Return Value 


Comments 


See Also 


This message has no parameters. 


An application should return nonzero if it can conveniently terminate; otherwise, it 
should return Zero. 


The DefWindowProc function returns nonzero when it processes this message. 


DefWindowProc, ExitWindows, WM _ENDSESSION 


WM_QUERYNEWPALETTE 


Parameters 


Return Value 


- Example 


WM_QUERYNEWPALETTE 


The WM_QUERYNEWPALETTE message informs an application that it is about 
to receive the input focus, giving the application an opportunity to realize its logi- 
cal palette when it receives the focus. 


This message has no parameters. 


An application should return nonzero if it realizes its logical palette; otherwise, it 
should return zero. 


This example shows how an application selects and realizes its logical palette: 


HDC hdc; 
HPALETTE hpalApp, hpalT; 
UINT 7; 


/* | 
* If this application changed the palette, ignore the message. 
x / 


case WM_PALETTECHANGED: | 
if (wParam == hwnd) 
return @L; 


/* Otherwise, fall through to WM_QUERYNEWPALETTE. */ 


See Also 
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case WM QUERYNEWPALETTE: 
/* , 

* If realizing the palette causes the palette to change, 

* redraw completely. 

* / 


hdc = GetDC(hwnd); | 
hpalT = SelectPalette (hdc, hpalApp, FALSE); 


j = RealizePalette(hdc); /* i == entries that changed */ 
SelectPalette (hdc, hpalT, FALSE); 

ReleaseDC(hwnd, hdc); 

/* If any palette entries changed, repaint the window. */ | 


if (i> @) 
InvalidateRect(hwnd, NULL, TRUE); 


return i; 


WM_PALETTECHANGED, WM_PALETTEISCHANGING 


WM_QUERYOPEN Po Ae eer 


Parameters — 


Return Value 


Comments 


WM_QUERYOPEN 


The WM_QUERYOPEN message is sent to a minimized window when the user 
requests that the window be restored to its preminimized size and position. 


This message has no parameters. 


An application that processes this message should return a nonzero value if the 
icon can be opened or zero to prevent the icon from opened. 


While processing this message, the application should not perform any action that 
would cause an activation or focus change (for example, creating a dialog box). 


The DefWindowProc function returns nonzero when it processes this message. 
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WM_QUEUESYNC ra] 


Parameters 
Return Value 


Comments 


WM_QUIT 


Parameters 


Return Value 


See Also 


WM_QUEUESYNC 


The WM_QUEUESYNC message is sent by a computer-based training (CBT) ap- 
plication to separate user-input messages from other messages sent through the 
journal playback hook (WH_JOURNALPLAYBACK). 


This message has no parameters. 
A CBT application should return zero if it processes this message. 


Whenever a CBT application uses the journal playback hook, the first and last mes- 
sages rendered are WM_QUEUESYNC. This allows the CBT application to inter- 
cept and examine user-initiated messages without doing so for events that it sends. 


WM_QUIT 
wExit = wParam; /* exit code */ 


The WM_QUIT message indicates a request to terminate an application and is 
generated when the application calls the PostQuitMessage function. It causes the 
GetMessage function to return zero. 


WExit | | 
Value of wParam. Specifies the exit code given in the PostQuitMessage func 


tion. | 


This message does not have a return value, because it causes the message loop to 
terminate before the message is sent to the application’s window procedure. 


GetMessage, PostQuitMessage 
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WM_RBUTTONDBLCLK cz) 


Parameters 


Return Value 


Comments 


See Also 


WM_RBUTTONDBLCLK 


fwkeys = wParam; /* key flags * / 
xPos = LOWORD(1Param) ; /* horizontal position of cursor */ 
yPos = HIWORD(1Param); - /* vertical position of cursor * / 


The WM_RBUTTONDBLCLK message is sent when the user double-clicks the 
right mouse button. | 


jwKeys | | 7 
Value of wParam. Indicates whether various virtual keys are down. This 
parameter can be any combination of the following values: 

Value Description 


MK_CONTROL Set if CTRL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON Set if middle button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


xPos | 
Value of the low-order word of lParam. Specifies the x-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


yPos , 
_ Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


An application should return zero if it processes this message. 


Only windows that have the CS_DBLCLKS class style can receive 
WM_RBUTTONDBLCLK messages. Windows generates a 
WM_RBUTTONDBLCLK message when the user presses, releases, and again 
presses the right mouse button within the system’s double-click time limit. 
Double-clicking the right mouse button actually generates four messages: a 
WM_RBUTTONDOWN message, a WM_RBUTTONUP message, the : 
WM_RBUTTONDBLCLK message, and another WM_RBUTTONUP message. 


WM_RBUTTONDOWN, WM_RBUTTONUP 
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WM_RBUTTONDOWN 


Parameters 


Return Value 


See Also 


WM_RBUTTONDOWN 


fwkeys = wParam; /* key flags * / 
xPos = LOWORD(1Param) ; /* horizontal position of cursor */ 
yPos. = HIWORD(1Param) ; /* vertical position of cursor * / 


The WM_RBUTTONDOWN message is sent when the user presses the right 


mouse button. 


fwKeys 


Indicates whether various virtual keys are down. This parameter can be any 


combination of the following values: 

Value Description 

MK_CONTROL Set if CTRL key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_SHIFT Set if SHIFT key is down. 


xPos 


Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 


sor. The coordinate is relative to the upper-left corner of the window. 


yPos 


Value of the high-order word of IParam. Specifies the y-coordinate of the cur- 


sor. The coordinate is relative to the upper-left corner of the window. 


An application should return zero if it processes this message. 


WM_RBUTTONDBLCLK, WM _RBUTTONUP 


WM_RBUTTONUP 


WM_RBUTTONUP. 


fwkeys = wParam; /* key flags * / 
xPos = LOWORD(1Param) ; /* horizontal position of cursor */ 
yPos = HIWORD(1Param) ; /* vertical position of cursor */ 


The WM_RBUTTONUP message is sent when the user releases the right mouse 


button. 
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Parameters. fwKeys 
Value of wParam. Indicates whether various virtual keys are down. This 
_ parameter can be any combination of the following values: 


Value Description 


MK_CONTROL Set if CTRL key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_ SHIFT Set if SHIFT key is down. | 


xPos 
Value of the low-order word of /Param. Specifies the x-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


yPos 
Value of the high-order word of /Param. Specifies the y-coordinate of the cur- 
sor. The coordinate is relative to the upper-left corner of the window. 


Return Value ~ An application should return zero if it processes this message. 


See Also WM_RBUTTONDBLCLK, WM_RBUTTONDOWN 
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WM_RENDERALLFORMATS 


The WM_RENDERALLFORMATS message is sent to the clipboard owner when 
the owner application is being destroyed. 


Parameters | This message has no parameters. 
Return Value An application should return zero if it processes this message. 
Comments The clipboard owner should render the data in all the formats it is capable of gener- 


ating and pass a data handle for each format to the clipboard by calling the Set- 
ClipboardData function. This ensures that the clipboard contains valid data even 
though the application that rendered the data is destroyed. The application should 
call the OpenClipboard function before calling SetClipboardData and should © 
call the CloseClipboard function afterward. 
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Example | In this example, the application sends a WM_RENDERFORMAT message to it- 
self for each clipboard format that the application supports: 


case WM_RENDERALLFORMATS: 
OpenClipboard(hwnd) ; 
SendMessage(hwnd, WM_RENDERFORMAT, CF_DIB, QL); 
SendMessage(hwnd, WM_RENDERFORMAT, CF_BITMAP, @L); 
CloseClipboard(); | 
break; , 


See Also CloseClipboard, OpenClipboard, SetClipboardData, WM_RENDERFORMAT 


WM_RENDERFORMAT [2x | 


WM_RENDERFORMAT 
uFmt = (UINT) wParan; /* clipboard data format */ 


The WM_RENDERFORMAT message is sent to the clipboard owner when a par- 
ticular format with delayed rendering needs to be rendered. The receiver should 
render the data in that format and pass it to the clipboard by calling the Set- 
ClipboardData function. 


Parameters uFmt | LS 
| Specifies the data format. It can be any one of the formats described with the 
SetClipboardData function. 


Return Value An application should return zero if it processes this message. 
Comments — The application should not call the OpenClipboard and CloseClipboard func- 
tions while processing this message. 
_ Example This example uses an application-defined function to render clipboard data. The 
function returns a data handle that is passed to the clipboard by the SetClipboard- 


Data function. 
HANDLE hData; 


case WM_RENDERFORMAT: 
if (hData = RenderFormat(wParam) ) 
SetClipboardData(wParam, hData); 
break; | | . 


See Also CloseClipboard, OpenClipboard, SetClipboardData, 
WM_RENDERALLFORMATS © 
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WM_SETCURSOR Or 


WM_SETCURSOR 


hwndCursor = (HWND) wParam; /* handle of window with cursor */ 
nHittest = LOWORD(1Param); /* hit-test code * / 
wMouseMsg = HIWORD(1Param); /* mouse-message number * / 


The WM_SETCURSOR message is sent to a window if mouse input is not cap- 
tured and the mouse causes cursor movement within the window. 


Parameters hwndCursor 
Value of wParam. Specifies a handle to the window that contains the cursor. 
nilittest | 
Value of the low-order word of /Param. Specifies the hit-test area code. 
wMouseMsg | 
Value of the high-order word of /Param. Specifies the number of the mouse 
message. . 
Return Value _ An application should return TRUE to halt further processing or FALSE to con- : 
| tinue. | | 
Comments If the nHittest parameter is HTERROR and the wMouseMsg parameter is a mouse 


button-down message, the MessageBeep function is called. 


‘The DefWindowProc function passes the WM_SETCURSOR message to a 
parent window before processing. If the parent window returns TRUE, further 
processing is halted. Passing the message to a window’s parent window gives the 
parent window control over the cursor’s setting in a child window. The Def- 
WindowProc function also uses this message to set the cursor to a pointer if it is 
not in the client area or to the registered-class cursor if it is in the client area. 


For a standard dialog box to set the cursor for one of its child window controls, it 
must force the DefDlgProc function to return TRUE in response to the WM_SET- 
CURSOR message. (DefDlgProc provides default processing for the standard 
dialog box class.) When DefDigProc returns TRUE, the dialog box procedure re- 
tains control over the cursor. When the dialog box procedure processes WM_SET- 
CURSOR, it can return TRUE by using the SetWindowLong function and the 
DWL_MSGRESULT offset, as shown in the following example: | 


SetWindowLong(hwndD1lg, DWL_MSGRESULT, MAKELONG(TRUE, @)); 


See Also DefWindowProc, MessageBeep, SetWindowLong 
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-WM_SETFOCUS re 


WM_SETFOCUS 
hwnd = (HWND) wParam; /* handle of window losing focus */ 


The WM_SETFOCUS message is sent after a window gains the input focus. © 


Parameters hwnd 


Value of wParam. Contains the handle of the window that loses the input focus. 
(This parameter may be NULL.) 


Return Value An application should return zero if it processes this message. 
Comments _ To display a caret, an application should call the appropriate caret functions at this 
point. 


-WM_SETFONT 


WM_SETFONT | 7 | 
wParam = (WPARAM) hfont; | /* handle of the font */ 
1Param = (LPARAM) MAKELONG( (WORD) fRedraw, @); /* redraw flag * / 


An application sends the WM_SETFONT message to specify the font that a con- 
trol is to use when drawing text. 


Parameters  hfont 
Value of wParam. Specifies the handle of the font. If this parameter is NULL, 
the control will use the default system font to draw text. 


{Redraw | 
Value of the low-order word of /Param. Specifies whether the control should 
be redrawn immediately upon setting the font. Setting the fRedraw parameter to 
TRUE causes the control to redraw itself. 


Return Value An application should return zero if it processes this message. 


Comments 


Example 
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The WM_SETFONT message applies to all controls, not just those in dialog boxes. 


The best time for the owner of a dialog box to set the font of the control is when it 
receives the WM_INITDIALOG message. The application should call the 
DeleteObject function to delete the font when it is no MuEet needed—for ex- 
ample, after the control is destroyed. 


The size of the control is not changed as a result of receiving this message. To pre- 
vent Windows from clipping text that does not fit within the boundaries of the con- 
trol, the application should correct the size of the control window before changing 
the font. 


Before Windows creates a dialog box with the DS_SETFONT style, Windows. 
sends the WM_SETFONT message to the dialog box window before creating the 
controls. An application creates a dialog box with the DS_SETFONT style by 
calling any of the following functions: 


=» CreateDialogIndirect 

=» CreateDialogIndirectParam 

# DialogBoxIndirect 

= DialogBoxIndirectParam 

The DialogBoxHeader structure that the application passes to these functions 


must have the DS_SETFONT style set and must contain the wPointSize and 
szFaceName members that define the font the dialog box will use to draw text. 


For more information about the DialogBoxHeader structure, see Chapter 7, 
“Resource Formats Within Executable Files,” in the Microsoft Windows 
Programmer s Reference, Volume 4. 


This example changes the font used by controls in a dialog box to a font that is not 
bold. 


HFONT hDlgFont; 
LOGFONT 1|Font; 


case WM_INITDIALOG: 


/* Get dialog box font and create version that is not bold. */ 
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See Also 


WM_ SETREDRAW 


Parameters 


Return Value 


| Comments 


hDigFont = (HFONT) NULL; : 
if ((hDlgFont = (HFONT) SendMessage(hdlg, WM_GETFONT, @, Q@L))) { 
if (GetObject(hDlgFont, sizeof(LOGFONT), (LPSTR) &lFont)) { 
1Font.1]fWeight = FW NORMAL; 
if (hDlgFont = CreateFontIndirect((LPLOGFONT) &lFont)) { 
SendDigItemMessage(hdlg, ID_CTRL1, WM_SETFONT, 
hDigFont, @L); 
SendDigItemMessage(hdlg, ID_CTRL2, WM_SETFONT, 
hDlgFont, @L); 


. /* Set font for remaining controls. */ 


} 
} 
return TRUE; 


CreateDialogIndirect, CreateDialogIndirectParam, DeleteObject, DialogBox- 
Indirect, DialogBoxIndirectParam 


WM_SETREDRAW 
wParam (WPARAM) fRedraw; /* state of redraw flag * / 
1Param OL; /* not used, must be zero */ 


An application sends a WM_SETREDRAW message to a window to allow 
changes in that window to be redrawn or to prevent changes in that window from 
being redrawn. 


fRedraw 


Value of wParam. Specifies the state of the redraw flag. If this parameter is 
nonzero, the redraw flag is set. If this parameter is zero, the flag is cleared. 


An application should return zero if it processes this message. 


This message sets or clears the redraw flag. If the redraw flag is cleared, the con- 
tents of the specified window will not be updated after each change, and the win- 
dow will not be repainted until the redraw flag is set. For example, an application 
that needs to add several items to a list box can clear the redraw flag, add the 
items, and then set the redraw flag. Finally, the application can call the 
InvalidateRect function to cause the list box to be repainted. 
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WM_SETTEXT a 


wParam = Q; /* not used, must be zero a / 
1Param = (LPARAM) (LPCSTR) pszText; /* address of window-text string */ 


An application sends a WM_SETTEXT message to set the text of a window. 


Parameters. pszText 
Value of /Param. Points to a null-terminated string that is the window text. 


Return Value The return value is LB_ERRSPACE (for a list box) or CB_ERRSPACE (for a 
- combo box) if insufficient space is available to set the text in the edit control. It is 
CB_ERR if this message is sent to a combo box without an edit control. 


Comments For an edit control, the text to be set is the contents of the edit control. For a — 
combo box, the text is the contents of the edit-control (or static-text) portion of the 
combo box. For a button, the text is the button name. For other windows, the text 
is the window title. : 


This message does not change the current selection in the list box of a combo box. 
An application should use the CB_SELECTSTRING message to select the item in 
the list box that matches the text in the edit control. , 


See Also WM _GETTEXT 


WM_SHOWWINDOW a 


fShow = (BOOL) wParam; | /* show/hide flag */ 
fnStatus = LOWORD(1Param) ; /* status flag ef 


The WM_SHOWWINDOW message is sent to a window when it is about to be 
hidden or shown. A window is hidden or shown when the ShowWindow function © 
is called; when an overlapped window is maximized or restored; or when an 

_ overlapped or pop- up window is minimized or displayed on the screen. When an — 
overlapped window is minimized, all pop- up windows associated with that win- 
dow are hidden. | 


Parameters — fShow. 
| Value of wParam. Specifies whether a window is Sone shown. It is TRUE if 
the window is ee shown; it 1S FALSE if the window is being hidden. 
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Return Value 


Comments 


See Also 


WM_SIZE 


Parameters 


JnStatus 
Value of the low-order word of lParam. Specifies the status of the window 
being shown. The fnStatus parameter is zero if the message is sent because of a 
Show Window function call; otherwise, fnStatus is one of the following values: 


Value Description 


SW_PARENTCLOSING Parent window is being minimized, or a pop-up 
window is being hidden. 

SW_PARENTOPENING Parent window is opening (being displayed) or a pop- 
up window is being shown. 


An application should return zero if it processes this message. 


The DefWindowProc function hides or shows the window as specified by the 
message. 


The WM_SHOWWINDOW message is not sent under the following circum- 
stances: 


m When a ae window is created with the WS_MAXIMIZE or WS_MINIMIZE 
style 


= When the SW_SHOWNORMAL flag is specified in the call to the Show- 
Window function 


DefWindowProc, ShowWindow 


WM_SIZE 


_fwSizeType = wParam; /* sizing-type flag * / 


nWidth = LOWORD(1Param); /* width of client area ¥*/ 
nHeight = HIWORD(1Param); /* height of client area */ 


The WM_SIZE message is sent to a window after its size has changed. 


fwSizeType 
Value of wParam. Specifies the type of resizing requested. This parameter can 
be one of the following values: 


~ Return Value 


Comments 


, See Also 


Value 


SIZE MAXIMIZED 
SIZE_ MINIMIZED 
SIZE_RESTORED 


SIZE_MAXHIDE 


SIZE_MAXSHOW 


nWidth 
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Description 


Window has been maximized. 

Window has been minimized. 

Window has been resized, but neither SIZE_MINIMIZED 
nor SIZE_MAXIMIZED applies. 

Message is sent to all pop-up windows when some other 
window is maximized. 

Message is sent to all pop-up windows when some other 
window has been restored to its former size. 


Value of the low-order word of lParam. Specifies the n new width of the client 


area. 


nHeight 


Value of the high-order word of lParam. Specifies ie new height of the client 


_ area. 


An application should return zero if it processes this message. 


Tf the SetScrollPos or MoveWindow function is called for a child window as a re- 


sult of the WM_SIZE message, the fRepaint parameter should be nonzero to cause 
the window to be repainted. 


WM_SIZECLIPBOARD 


Parameters 


 WM_SIZECLIPBOARD ee ae 
~ hwndViewer = (HWND) wParam; /* handle of clipboard viewer */ 


| MoveWindow. SetScrollPos 


[2x] 


hglb = (HGLOBAL) LOWORD(1Param); /* handle of global object * / 


The WM_SIZECLIPBOARD message is sent by the clipboard viewer to the clip- 
board owner when the clipboard contains data with the CF_OWNERDISPLAY 
attribute and the size of the client area of the chpboatd: viewer window has — 


changed. 


hwndViewer 


_ Value of wParam. Identifies the lipboard-appication window. 
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hglb 
Value of the low-order word of /Param. Identifies a global memory object that 
contains a RECT data structure. The structure specifies the area that the clip- 
board owner should paint. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


Return Value An application should return zero if it processes this message. 


Comments A WM_SIZECLIPBOARD message is sent with a null rectangle (0,0,0,0) as the 
new size when the clipboard application is about to be destroyed or minimized. 
This permits the clipboard owner to free its display resources. 


An application must use the GlobalLock function to lock the memory that con- 
tains the RECT data structure. The application should unlock that memory by 
using the GlobalUnlock function before it yields or returns control. 


See Also GlobalLock, GlobalUnlock, SetClipboardData, SetClipboard Viewer 


WM_SPOOLERSTATUS a 


WM_ SPOOLERSTATUS 
fwJobStatus = wParam; /* job-status flag ef 
cJobsLeft = LOWORD(1Param); /* number of jobs remaining */ 


The WM_SPOOLERSTATUS message is sent from Print Manager whenever a 
job is added to or removed from the Print Manager queue. 


Parameters fwJobStatus — 
Value of wParam. Specifies the SP_JOBSTATUS flag. 


cJobsLeft 
Value of the low-order word of /Param. Specifies the number of jobs oe 
in the Print Manager queue. 


Return Value An application should return zero if it processes this message. 


Comments This message is for informational purposes only. 
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WM_SYSCHAR ware a 


_ Parameters 


Return Value — 


Comments 


WM_SYSCHAR 
wKeyCode = wParam; /* ASCII key code */ 
dwkeyData = 1Param; /* key data * / 


‘The WM_SYSCHAR message is sent to the window with the input focus when a 


WM_SYSKEYUP and a WM_SYSKEYDOWN message are translated. It speci- 
fies the virtual-key code of the System-menu key. (The System menu is some- 
times referred to as the Control menu.) 


wKeyCode 
Value of wParam. Specifies the ASCII- character key code of a System-menu 
key. | | 


dwKeyData 
Value of /Param. Specifies the repedt count, scan code, extended key, context 
code, previous key state, and key-transition state, as shown in the following 
table: 7 


Bit —sC*Descrription : | 
0-15. Specifies the repeat count. The value is the number of times the keystroke — 


is repeated as a result of the user holding down the key. - 


16-23 Specifies the scan code. The value cspence on the © original equipment | 
manufacturer (OEM). 
24 Specifies whether the key is an extended key, such as a function key ora 
ma key on the numeric keypad. The value is 1 if it is an extended key; other- 
wise, it is 0. 
25-26 Not used. 


27-28 Used internally by Windows. 


29 Specifies the context code. The value is 1 if the ALT key is held down 
at while the key is pressed; otherwise, the value is 0. | | 

30 Specifies the previous key state. The value is 1 if the key is down before © 
| | the message is sent, or it is 0 if the key is up. | 

31 Specifies the key-transition state. The value is 1 if the key is being Te- 


leased, or it is 0 if the key is being pressed. 


An application should return zero if it processes this message. 


When the context code is zero, the message can be passed to the Translate- 
Accelerator function, which will handle it as though it were a normal key mes- 
sage instead of a System-menu key message. This allows accelerator keys to be 


used with the active window even if the active window does not have the input 


focus. 


198 WM_SYSCOLORCHANGE 


See Also 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
key and the right CTRL key on the main section of the keyboard; the INS, DEL, 
HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the 
numeric keypad; and the division (/) and ENTER keys on the numeric keypad. Some 
other keyboards may support the extended-key bit in the /Param parameter. 


TranslateAccelerator, WM_SYSKEYDOWN, WM_SYSKEYUP 


WM_SYSCOLORCHANGE a (2x 


Parameters 
Return Value 


Comments 


See Also 


WM_SYSCOLORCHANGE 


The WM_SYSCOLORCHANGE message is sent to all top-level windows when a 
change is made in the system color setting. 


This message has no parameters. 
An application should return zero if it processes this message. 


Windows sends a WM_PAINT message to any window that is affected by a sys- 
tem color change. 


Applications that have brushes that use the existing system colors should delete 
those brushes and re-create them by using the new system colors. 


SetSysColors, WM_PAINT 


WM_SYSCOMMAND ex] 


WM_SYSCOMMAND 


wCmdType = wParam; /* command value * / 
xPos = LOWORD(1Param); /* horizontal position of cursor */ 
yPos = HIWORD(1Param) ; /* vertical position of cursor * / 


The WM_SYSCOMMAND message is sent when the user selects a command 
from the System menu (sometimes referred to as the Control menu) or when the 
user selects the Maximize button or the Minimize button. 
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Parameters | wCmdType | 
| Value of wParam. Specifies the type of system command requested. This 
parameter can be one of the following values: 


Value Meaning — 
SC_CLOSE | Close the window. 
SC_HOTKEY Activate the window associated with the 


application-specified hot key. The low-order 
word of [Param identifies the window to 


activate. 
SC_HSCROLL Scroll horizontally. 
SC_KEYMENU Retrieve a menu through a keystroke. 
SC_MAXIMIZE (or SC_ZOOM) Maximize the window. 
SC_MINIMIZE (or SC_ICON) Minimize the window. 
~ SC_MOUSEMENU Retrieve a menu through a mouse click. 
SC_MOVE Move the window. 7 
SC_NEXTWINDOW Move to the next window. 
SC_PREVWINDOW _. Move to the previous window. 
$C _RESTORE | | ~ Restore window to normal position and size. 
| SC_SCREENSAVE Execute the screen-saver application specified 
¢ | | =. in the [boot] section of the SYSTEM. INI file. 
SC_SIZE — Size the window. _ 
_ SC_TASKLIST | : Execute or activate the Windows Task 
| | a . Manager application. | 
SC_VSCROLL © Scroll vertically. 


xPos 
Value of the low-order word of lParam. Specifies tt the x-coordinate of the cur- 
sor, ifa System-menu command is chosen with the mouse. Otherwise, this 
parameter is not used. : | 


yPos 
Value of the high-order word of /Param. Specifies the y- -coordinate of the cur- 
sor, ifa System- -menu command i 1S chosen with the mouse. Otherwise, this — 
parameter is not used. . 


Return Value An application stoutd return zero if it processes this message, 


Comments The DefWindowProc function carries out the System-menu request for the prede- 
fined actions specified i in the preceding table. ; 


In WM _SYSCOMMAND messages, the four low- order bits of the wCnidType 
parameter are used internally by Windows. When an application tests the value of 
wCmdType, it must combine the value OxFFFO with the wCmdType value by using 
the bitwise AND operator to obtain the correct result. 
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The menu items in a System menu can be modified by using the GetSystem- 
Menu, AppendMenu, InsertMenu, and ModifyMenu functions. Applications 
that modify the System menu must process WM_SYSCOMMAND messages. 
Any WM_SYSCOMMAND messages not handled by the application must be 
passed to the DefWindowProc function. Any command values added by an appli- 
cation must be processed by the application and cannot be passed to DefWindow- 
Proc. 


An application can carry out any system command at any time by passing a 
WM_SYSCOMMAND message to the DefWindowProc function. | 


Accelerator keystrokes that are defined to select items from the System menu are 
translated into WM_SYSCOMMAND messages; all other accelerator key strokes 
are translated into WM_COMMAND messages. 


See Also AppendMenu, DefWindowProc, GetSystemMenu, InsertMenu, ModifyMenu, 
WM_COMMAND 


WM_SYSDEADCHAR ri} 


WM_SYSDEADCHAR 

wDeadKey = wParam; /* dead-key character */ 
cRepeat = (int) LOWORD(1Param); /* repeat count * / 
cAutoRepeat = HIWORD(1Param) ; /* autorepeat count ¥*/ 


The WM_SYSDEADCHAR message is sent to the window with the input focus 
when WM_SYSKEYUP and WM_SYSKEYDOWN messages are translated. It 
specifies the character value of a dead key. 


Parameters wDeadKey | 
| Value of wParam. Specifies the dead-key character value. 


cRepeat 
Value of the low-order word of /Param. Specifies the repeat count. 


cAutoRepeat 
Value of the high-order word of /Param. Specifies the auto-repeat count. 


Return Value An application should return zero if it processes this message. 


See Also WM_SYSKEYDOWN, WM_SYSKEYUP 
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WM_SYSKEYDOWN es 


Parameters 


Return Value 


WM_SYSKEYDOWN 
wVkey = wParam; /* virtual-key code */ 
dwKkeyData = ]Param; /* key data x / 


The WM_SYSKEYDOWN message is sent to the window with the input focus 
when the user holds down the ALT key and then presses another key. If no window 
currently has the input focus, the WM_SYSKEYDOWN message is sent to the ac- 
tive window. The window that receives the message can distinguish between these 
two contexts by checking the context code in the dwKeyData parameter. 


wVkey 
Value of wParam. Specifies the virtual-key code of the key being pressed. 


dwKeyData 
Value of /Param. Specifies the repeat count, scan code, extended key, context 
code, previous key state, and key-transition state, as shown in the following 
table: 


Bit Description 
0-15 Specifies the repeat count. The value is the number of times the keystroke 
is repeated as a result of the user holding down the key. 


16-23 Specifies the scan code. The value depends on the original equipment 
manufacturer (OEM). 


24 Specifies whether the key is an extended key, such as a function key or a 
key on the numeric keypad. The value is 1 if itis an extended key; other- 
wise, it is 0. 

25-26 Not used. 

27-28 Used internally by Windows. 

29 Specifies the context code. The value is 1 if the ALT key is held down 
while the key is pressed; otherwise, the value is 0. 

30 Specifies the previous key state. The value is 1 if the key is down before 
the message is sent, or it is O if the Key is up. 


31 Specifies the key-transition state. The value is 1 if the key is being re- 
leased, or it is 0 if the key is being pressed. 


For WM_SYSKEYDOWN messages, the value of bit 29 (context code) 1 is lif 
the ALT key is down while the key is pressed; it is 0 if the message is sent to the 
active window because no window has the input focus. The value of bit 31 (key- 
transition state) is 0. 


An application should return zero if it processes this message. 
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Comments When the context code is zero, the message can be passed to the Translate- 
Accelerator function, which will handle it as though it were a normal key mes- 
sage instead of a system-key message. This allows accelerator keys to be used 
with the active window even if the active window does not have the input focus. 


Because of the autorepeat feature, more than one WM_SYSKEYDOWN message 
may occur before a WM_SYSKEYUP message is sent. The previous Key state (bit 
30) can be used to determine whether the WM_SYSKEYDOWN message indi- 
cates the first down transition or a repeated down transition. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
key and the right CTRL key on the main section of the keyboard; the INS, DEL, 
HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the 
numeric keypad; and the division (/) and ENTER Keys on the numeric keypad. Some 
other keyboards may support the extended-key bit in the [Param parameter. 


See Also TranslateAccelerator, WM_SYSKEYUP 


WM_SYSKEYUP = ax 


wVkey = wParam; /* virtual-key code */ 
dwKeyData = 1Param; /* key data ——_ 


The WM_SYSKEYUP message is sent to the window with the input focus when 
the user releases a key that was pressed while the ALT key was held down. If no 
window currently has the input focus, the WM_SYSKEYUP message is sent to 
the active window. The window that receives the message can distinguish between 
these two contexts by checking the context code in the /Param parameter. 


Parameters wVkey 
Value of wParam. Specifies the virtual-key code of the key being pressed. 


dwKeyData 
Value of lParam. Specifies the repeat count, scan code, extended key, context 
code, previous key state, and key-transition state, as shown in the following 


table: 
Bit Description | 
0-15 Specifies the repeat count. The value is the number of times the keystroke 


is repeated as a result of the user holding down the key. 


16-23 Specifies the scan code. The value depends on the original equipment 
manufacturer (OEM). 


Return Value 


Comments 


See Also 
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Bit Description 

24 Specifies whether the key is an extended key, such as a function key or a 
key on the numeric keypad. The value is 1 if itis an extended key; other- 
wise, it is 0. 


25-26 Not used. 

27-28 Used internally by Windows. 

29 Specifies the context code. The value is 1 if the ALT key is held down 
while the key is pressed; otherwise, the value is 0. . 

30 Specifies the previous key state. The value is 1 if the key i 1S down before 
the message is sent, or it is 0 if the key is up. | 


31 Specifies the key-transition state. The value is 1 if the key is being re- 
leased, or it is 0 if the key is being pressed. 


For WM_SYSKEYUP messages, the value of bit 29 (context code) is | if the 
ALT key is down while the key is pressed; it is 0 if the message is sent to the 
active window because no window has the input focus. The value of bit 31 
(key-transition state) is 1. 


An application should return zero if it processes this message. 


When the context code is zero, the message can be passed to the Translate- 
Accelerator function, which will handle it as though it were a normal key mes- 
sage instead of a system-key message. This allows accelerator keys to be used 
with the active window even if the active window does not have the input focus. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
key and the right CTRL key on the main section of the keyboard; the INS, DEL, 


_ HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the 


numeric keypad; and the division (/) and ENTER keys on the numeric keypad. Some 
other keyboards may support the extended-key bit in the /Param parameter. 


For non-U.S. Enhanced 102-key keyboards, the right ALT key is handled as the 
CTRL+ALT key combination. The following list shows the messages that result 
when the user presses and releases this key, in the sequence they occur: 


WM_KEYDOWN VK_CONTROL 
WM_KEYDOWN VK_MENU 
WM_KEYUP VK_CONTROL 
WM_SYSKEYUP VK_MENU 


TranslateAccelerator, WM_SYSKEYDOWN 
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WM_SYSTEMERROR to Age 


WM_SYSTEMERROR 7 
wErrSpec = wParam; /* specifies when error occurred */ 


The WM_SYSTEMERROR message is sent when the Windows kernel encounters 
an error but cannot display the system-error message box. 


Parameters wErrSpec 
Value of wParam. Specifies when the error r occurred. Currently, the only valid 
value is 1, indicating that the error occurred when a task or library was terminat- 


ing. 
Return Value An application should return zero if it processes this message. 
Comments A shell application should process this message, displaying a message box that in- 


dicates an error has occurred. 


WM_TIMECHANGE [2x 


WM_ TIMECHANGE 
wParam = Q; /* not used, must be zero */ 
1Param = QL; /* not used, must be zero */ 


An application sends the WM_TIMECHANGE message to all top- ve windows 
after changing the system time. 


Parameters This message has no parameters. 
Return Value An application should return zero if it processes this message. 
Comments Any application that changes the system time should send this message to all top- 


level windows. To send the WM_TIMECHANGE message to all top-level win- 
dows, an application can use the SendMessage function with the hwnd parameter 
set to HWND_ BROADCAST. 


See Also SendMessage 
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WM_TIMER LR 


WM_TIMER © 
wlimerID = wParam; /* timer identifier * / 
tmprc = (TIMERPROC FAR*) 1Param; /* address of timer callback * / 


The WM_TIMER message is posted to the installing application’s message queue 
or sent to the appropriate TimerProc callback function after each interval 
specified in the SetTimer function used to install a timer. 


Parameters wTimerID | 
Value of wParam. Specifies the identifier of the timer. 


tmprc 
Value of /Param. Points to a callback function that was passed to the SetTimer 
function when the timer was installed. If the tmprc parameter is not NULL, the 
system passes the WM_TIMER message to the specified callback function 
rather than posting the message to the application’s message queue. 


Return Value An application should return zero if it processes this message. 


Comments The DispatchMessage function sends this message when no other messages are in 
the application’s message queue. 


Example _ This example uses the WM_TIMER message to create a blinking effect for a line 
of text: 


DWORD dwXYVal; 
WORD wXVal, wYVal; 
char szMessage[16]; 


case WM_TIMER: 
hdc = GetDC(hwnd); 
dwXYVal = GetTextExtent(hdc, (LPCSTR) szMessage, 

Istrlen(szMessage)); : 

wXVal = LOWORD(dwXYVal); 
wYVal = HIWORD(dwXYVal); 
PatBlt(hdc, 10, 10, (int) wXVal, (int) wYVal, PATINVERT); 
ReleaseDC(hwnd, hdc); : 
ValidateRect(hwnd, NULL); 
break; 


‘See Also | SetTimer, TimerProc 
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WM_UNDO 


Parameters 


Return Value 


See Also 


[ 2x | 


WM_UNDO 

An application sends the WM_UNDO message to an edit control to undo the last 
operation. When this message is sent to an edit control, the previously deleted text 
is restored or the previously added text is deleted. 


This message has no parameters. 


The return value is nonzero if the operation is successful, or it is zero if an error 
occurs. 


WM_CLEAR, WM_COPY, WM_CUT, WM_PASTE 


WM_USER 


Comments 


[ 2.x | 


WM_USER 


WM_USER is a constant used by applications to help define private messages. 


The WM_USER constant is used to distinguish between message values that are 
reserved for use by Windows and values that can be used by an application to send 
messages within a private window class. There are four ranges of message num- 
bers: 


Range Meaning 

0 through WM_USER — 1 Messages reserved for use by Windows. 
WM_USER through 0x7FFF Integer messages for use by private window classes. 
0x8000 through OXBFFF Messages reserved for use by Windows. 
OxCO000 through OxFFFF — String messages for use by applications. 


Message numbers in the first range (0 through WM_USER - 1) are defined by 
Windows. Values in this range that are not explicitly defined are reserved for 
future use by Windows. This chapter describes messages in this range. 


Message numbers in the second range (WM_USER through 0x7FFF) can be de- 
fined and used by an application to send messages within a private window class. 
These values cannot be used to define messages that are meaningful throughout an 
application, because some predefined window classes already define values in 

this range. For example, such predefined control classes as BUTTON, EDIT, 


See Also 
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LISTBOX, and COMBOBOX may use these values. Messages in this range 
should not be sent to other applications unless the applications have been designed 
to exchange messages and to attach the same meaning to the message numbers. 


Message numbers in the third range (0x8000 through OxBFFF) are reserved for 
future use by Windows. 


Message numbers in the fourth range (OxC000 through OxXFFFF) are defined at run | 
time when an application calls the Register Window Message function to obtain a 
message number for a string. All applications that register the same string can use 
the associated message number for exchanging messages. The actual message 
number, however, is not a constant and cannot be assumed to be the same in differ- 


~ ent Windows sessions. 


Register WindowMessage 


WM_VKEYTOITEM 


Parameters 


Return Value 


WM_VKEYTOITEM 


wVkey = wParam; , /* virtual-key code 2 / 
hwndLB = (HWND) LOWORD(1Param) ; /* handle of the list box */ 
nCaretPos = HIWORD(1Param) ; /* caret position * / 


The WM_VKEYTOITEM message is sent by a list box with the 
LBS_WANTKEYBOARDINPUT style to its owner in response to a 
WM_KEYDOWN message. 


wVkey 
Value of wParam. Specifies the virtual-key code of the key that the user 
pressed. 


hwndLB 
Value of the low-order word of lParam. Identifies the list box. 


nCaretPos | 
Value of the high-order word of [Param. Specifies the current position of the 
caret. 


The return value specifies the action that the application performed in response to 
the message. A return value of —2 indicates that the application handled all aspects 
of selecting the item and requires no further action by the list box. A return value 


of —1 indicates that the list box should perform the default action in response to 


the keystroke. A return value of 0 or greater specifies the zero-based index of an 
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Comments 


See Also 


WM_VSCROLL 


Parameters 


item in the list box and indicates that the list box should perform the default action 
for the keystroke on the given item. 


Only list boxes that have the LBS_HASSTRINGS style can receive this message. 


WM_CHARTOITEM, WM_KEYDOWN 


WM_VSCROLL 
wScrol1Code = wParam; /* scroll bar code * / 
nPos = LOWORD(1Param); /* current scroll box position */ 


hwndCtl = (HWND) BIMORDC TEA ramys /* handle of the control */ 


The WM_VSCROLL message is sent to a window when the user clicks the win- 
dow’s vertical scroll bar. 


wScrollCode 
Value of wParam. Specifies a scroll bar code that indicates the user’s scrolling 
request. This parameter can be one of the following values: 


Value Description 
SB_BOTTOM Scroll to bottom. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_LINEUP Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 
SB_PAGEUP Scroll one page up. 


SB_THUMBPOSITION Scroll to absolute position. The current position is 
specified by the nPos parameter. 


SB_THUMBTRACK Drag scroll box (thumb) to specified position. The 
current position is specified by the nPos parameter. 
SB_TOP ~ Scroll to top. 
nPos 


Value of the low-order word of /Param. Specifies the current position of the. 
scroll box if wScrollCode is SB_THUMBPOSITION or SB_THUMBTRACK; 
otherwise, this Paraictes is not used. 
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hwndCtl 
Value of the high-order word of /Param. Identifies the control if 
WM_VSCROLL is sent by a scroll bar. If WM_VSCROLL is sent as a result of 
the user clicking a pop-up window’ scroll bar, the high-order word is not used. 


Return Value An application should return zero if it processes this message. 


Comments The SB_THUMBTRACK message typically i is used by applications that give 
some feedback while the scroll box is being dragged. 


If an application scrolls the contents of the window, it must also reset the position 
of the scroll box by using the SetScrollPos function. 


See Also SetScrollPos, WM_HSCROLL 


WM_VSCROLLCLIPBOARD ue BP Pa 


WM_ VSCROLLCLIPBOARD a | 
hwndViewer = (HWND) wParam; = /#* handle of clipboard viewer */ 


wScrol1lCode = LOWORD(1Param); /* scroll bar code | * / 


wlhumbPos = HIWORD(1Param); | /* scroll box position * / 


The WM_HSCROLLCLIPBOARD message is sent by the clipboard viewer to the 
clipboard owner when the clipboard data has the CF_OWNERDISPLAY format 
and there is an event in the clipboard viewer’s vertical scroll bar. The owner 
should scroll the clipboard image, invalidate the ae section, and update 
the scroll bar values. | 


Parameters | hwndViewer 
Value of wParam. Specifies a handle to a ite ie ret window. 
wScrollCode 
Value of the low-order word of lParam. Specifies one of the following scroll 
bar values: 
Value: Description 
SB_ BOTTOM Scroll to lower right. 
SB_ENDSCROLL End scroll. | 
SB. LINEDOWN Scroll one line down. 
SB_LINEUP ~ Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 


SB_PAGEUP | Scroll one page up. 
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Value | Description 

SB_THUMBPOSITION Scroll to absolute position. 

SB_TOP Scroll to upper left. 
wThumbPos 


Value of the high-order word of Param. Specifies the scroll box position if the 
scroll bar code is SB_THUMBPOSITION; otherwise, the high-order word is 


not used. 
Return Value An application should return zero if it processes this message. 
Comments The clipboard owner should use the InvalidateRect function or repaint the win- 


dow as needed. The scroll bar position should also be reset. 


See Also InvalidateRect, WM_HSCROLLCLIPBOARD 


WM_WINDOWPOSCHANGED BA] 


WM_WINDOWPOSCHANGED 
pwp = (const WINDOWPOS FAR*) 1Param; /* structure address ae / 


The WM_WINDOWPOSCHANGED message is sent to a window whose size, 
position, or z-order has changed as a result of a call to SetWindowPos or another 
window-management function. 


Parameters pwp 


Value of /Param. Points toa WINDOWPOS data structure that contains infor- 
mation about the window’s new size and position. The WINDOWPOS struc- 
ture has the following form: 


typedef struct tagWINDOWPOS { /* wp */ 


HWND hwnd; 

HWND hwndInsertAfter; 
int xs 

int y3 

int ACK 

int Cy; 


UINT flags; 
} WINDOWPOS; 


Return Value An application should return zero if it processes this message. 
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Comments The DefWindowProc function, when it processes the 
7 WM_WINDOWPOSCHANGED message, sends the WM_SIZE and 
WM_MOVE messages to the window. These messages are not sent if an 
_application handles the WM_WINDOWPOSCHANGED message without calling 
DefWindowProc. It is more efficient to perform any move or size change pro- 
cessing during the WM_WINDOWPOSCHANGED message without calling 
DefWindowProc. 


See Also WM_MOVE, WM_SIZE, WM_WINDOWPOSCHANGING 


WM_WINDOWPOSCHANGING a) 


WM_WINDOWPOSCHANGING 
pwp = (WINDOWPOS FAR*) 1Param; /* address of WINDOWPOS structure */ 


-The WM_WINDOWPOSCHAN GING message is sent to a window whose size, 
position, or z-order is about to change as a result of a call to SetWindowPos or 
another window- -management function. 


Parameters DWP ae reg ee oe Tees! 
| Value of [Param. Points toa WINDOWPOS data structure that contains infor- 
mation about the window’s new size and position. The WINDOWPOS struc- 
ture has the following form: 


typedef struct tagWINDOWPOS { /* wp */ 


HWND hwnd; 

HWND hwndInsertAfter; 
int De 7 

int y3 

int Cx’ 

int Cy; 


UINT flags; 
— } WINDOWPOS; 


Return Value — An application should return zero if it processes this message. 


Comments | During this message, modifying any of the values in the WINDOWPOS structure 
eae e affects the new size, position, or z-order. An application can prevent changes to 
the window by setting or clearing the appropriate bits in the flags member of the 
WINDOWPOS structure. 


For a window with the WS_OVERLAPPED or WS_THICKFRAME style, the 
DefWindowProc function handles a WM_WINDOWPOSCHANGING message 
__ by sending a WM_GETMINMAXINFO message to the window. This is 7 


212. WM_WININICHANGE 


done to validate the new size and position of the window and to enforce the 
CS_BYTEALIGNCLIENT and CS_BYTEALIGN client styles. An application 
can override this by not passing the WM_WINDOWPOSCHANGING message 
to the DefW indowProc function. 


See Also WM_WINDOWPOSCHANGED 


WM_WININICHANGE fe 


WM_WININICHANGE 
wParam = Q@; /* not used, must be zero */ 
1Param = (LPARAM) (LPCSTR) pszSection; /* address of string * / 


An application sends the WM_WININICHANGE message to all top-level win- 
dows after making a change to the Windows initialization file, WIN.INI. The 
SystemParametersInfo function sends the WM_WININICHANGE message 
after an application uses the function to change a setting in the WIN.INI file. 


Parameters pszSection 
Value of /Param. Points to a string that species the name of the section that 
has changed (the string does not include the square brackets that enclose the sec- 


tion name). 
~ Return Value An application should return zero if it processes this message. 
Comments To send the WM_WININICHANGE message to all top-level windows, an appli- 


cation can use the SendMessage function with the hwnd parameter set to 
HWND_BROADCAST. 


If an application changes many different sections in WIN.INI at the same time, 
the application should send the WM_WININICHANGE message once with the 
pszSection parameter set to NULL. Otherwise, an application should send a sepa- 
rate WM_WININICHANGE message for each change it makes to WIN. INI. 


If an application receives a WM_WININICHANGE message with the pszSection 


parameter set to NULL, the application should check all sections in WIN.INI that 
affect the application. 


See Also Send Message, SystemParametersInfo 
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2.2 Notification Messages 


Notification messages notify a control’s parent window of actions that occur 
within the control. Controls use the WM_COMMAND message to notify the 
parent window of actions that occur within the control. The wParam parameter of 
the WM_COMMAND message contains the control identifier; the low-order word 


_ of the /Param parameter contains the handle of the control; and the high-order 


word of [Param contains the control notification message. 


This section lists notification messages in alphabetic order. 


BN CLICKED a ee] 


See Also 


BN_CLICKED 


_ The BN_CLICKED notification message is sent when the user clicks a button. 


This notification is provided for compatibility with applications written prior to 


_ Windows version 3.0. New applications should use the BS_OWNERDRAW but- 


ton style and the DRAWITEMSTRUCT structure for this task. 


| DRAWITEMSTRUCT, WM_DRAWITEM 


BN DISABLE Recae tS 2 or ee ee 


See Also 


BN_DISABLE 


The BN_DISABLE notification message is sent when a button is disabled. This 
notification is provided for compatibility with applications written prior to Win- 
dows version 3.0. New applications should use the BS_OWNERDRAW button 
style and the DRAWITEMSTRUCT structure for cus task. 


~ DRAWITEMSTRUCT, WM_DRAWITEM 3 


214 BN_DOUBLECLICKED | 


BN_DOUBLECLICKED [ex] 


BN_DOUBLECLICKED 


The BN_DOUBLECLICKED notification message is sent when the user double 
clicks a button. This notification is provided for compatibility with applications 
written prior to Windows version 3.0. New applications should use the 
BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for 
this task. 


See Also DRAWITEMSTRUCT, WM_DRAWITEM 


BN_HILITE [2x] 


BN_HILITE 
The BN_HILITE notification message is sent when the user highlights a button. 
This notification is provided for compatibility with applications written prior to 


Windows version 3.0. New applications should use the BS_OWNERDRAW but- 
ton style and the DRAWITEMSTRUCT structure for this task. 


See Also DRAWITEMSTRUCT, WM_DRAWITEM 


BN PAINT ge 


BN_PAINT 


The BN_PAINT notification message is sent when a button should be painted. 
This notification is provided for compatibility with applications written prior to 

_ Windows version 3.0. New applications should use the BS_OWNERDRAW but- 
ton style and the DRAWITEMSTRUCT structure for this task. 


~ See Also DRAWITEMSTRUCT, WM_DRAWITEM 


CBN_CLOSEUP) =215 


BN_UNHILITE Secs Gat 


BN_UNHILITE 


The BN_UNHILITE notification message is sent when the highlight should be re- 
moved from a button. This notification is provided for compatibility with applica- 
tions written prior to Windows version 3.0. New applications should use the 
BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for 
this task. 


See Also DRAWITEMSTRUCT, WM_DRAWITEM 


CBN_CLOSEUP aie) rit 
The CBN _CLOSEUP notification message is sent when the list box of a combo. 


_ box is hidden. The control’s parent window receives this notification message 
through a WM_COMMAND message. 


~ Parameters | wParam 
ae Specifies the identifier of the combo box. 


lParam ae Ss 
Specifies the handle of the combo box in the low-order word, and specifies the 
CBN_CLOSEUP notification message in the high-order word. 


Comments This notification message is not sent to a combo box that has the CBS_SIMPLE 
style. 


The order in which notifications will be sent cannot be predicted. In parti- 
cular, a CBN_SELCHANGE notification may occur either before or after a 
CBN_CLOSEUP notification. 


See Also CBN_DROPDOWN, CBN_SELCHANGE, WM COMMAND 


216 CBN_DBLCLK 


CBN_DBLCLK a 


The CBN_DBLCLK notification message is sent when the user double-clicks a 
string in the list box of a combo box. The control’s parent window receives this 
notification message through a WM_COMMAND message. 


Parameters | wParam 
Specifies the identifier of the combo box. 
lParam : 


Specifies the handle of the combo box in the low-order word and the 
CBN_DBLCLK notification message in the high-order word. 


Comments This notification message can occur only for a combo box with the CBS_SIMPLE 
style. For a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST 
style, a double-click cannot occur because a single click hides the list box. 


See Also CBN_SELCHANGE, WM_COMMAND 


CBN_ DROPDOWN 


The CBN_DROPDOWN notification message is sent when the list box of a 
combo box is about to be dropped down (made visible). The parent window of the 
combo box receives this notification message through a WM_COMMAND mes- 
Sage. 


Parameters wParam 
Specifies the identifier of the combo box. 


lParam 
Specifies the handle of the combo box in the low-order word, and specifies the 
CBN_DROPDOWN notification message in the high-order word. 


Comments This notification message can occur only for a combo box with the 
) CBS_DROPDOWN or CBS_DROPDOWNLIST style. 


See Also CBN_CLOSEUP, WM_COMMAND 


CBN_EDITUPDATE 217 


CBN_EDITCHANGE [a0] 


The CBN_EDITCHANGE notification message is sent after the user has taken an 
action that may have altered the text in the edit-control portion of a combo box. 
Unlike the CBN_EDITUPDATE notification message, this notification message is 
sent after Windows updates the screen. The parent window of the combo box re- 
ceives this notification message through a WM_COMMAND message. 


Parameters wParam 
Specifies the identifier of the combo box. 


[Param 
Specifies the handle of the combo box in the low-order word, and specifies the 
CBN_EDITCHANGE notification message in the high-order word. 


Comments This message does not occur if the combo box has the CBS_DROPDOWNLIST 


style. | 
See Also CBN_EDITUPDATE, WM_COMMAND 


CBN_EDITUPDATE ee 8 


The CBN_EDITUPDATE notification message is sent when the edit-control por- 
tion of a combo box is about to display altered text. This notification is sent after 
the control has formatted the text, but before it displays the text. The parent win- 
dow of the combo box receives this notification message through a 
WM_COMMAND message. 


Parameters wParam 
_-_ Specifies the identifier of the combo box. 


lParam | 
Specifies the handle of the combo box in the low-order word, and specifies the 
CBN_EDITUPDATE notification message in the high-order word. 


Comments This message does not occur if the combo box has the CBS_DROPDOWNLIST 
style. | | 


See Also CBN_EDITCHANGE, WM_COMMAND 


218 CBN_ERRSPACE 


CBN ERRSPACE iat 


The CBN_ERRSPACE notification message is sent when a combo box cannot 
allocate enough memory to meet a specific request. The parent window of the 
combo box receives this notification message through a WM_COMMAND mes- 
Sage. 


Parameters wParam | 
7 Specifies the identifier of the combo box. 


lParam 


Specifies the handle of the combo box in the low-order word, and specifies the 
CBN_ERRSPACE notification message in the high-order word. 


See Also WM. COMMAND 


CBN_KILLFOCUS a0] 


The CBN_KILLFOCUS notification message is sent when a combo box loses the 
input focus. The parent window of the combo box receives this notification mes- 
sage through a WM_COMMAND message. 


Parameters wParam 
Specifies the identifier of the combo box. 


lParam ) 
Specifies the handle of the combo box in the low-order word, and specifies the 
CBN_KILLFOCUS notification message in the high-order word. 


See Also CBN_SETFOCUS, WM_COMMAND 


CBN_SELCHANGE he feo 


The CBN_SELCHANGE notification message is sent when the selection in the 
list box of a combo box is about to be changed as a result of the user either click- 
ing in the list box or changing the selection by using the arrow keys. The parent 
window of the combo box receives this code through a WM_COMMAND 
message. 


Parameters 


See Also 


CBN_SELENDOK 219 


wParam 
Specifies the identifier of the combo box. 


[Param 
Specifies the handle of the combo box in the low-order word, and specifies the 
CBN_SELCHANGE notification message in the high-order word. 


CBN_DBLCLK, CB_SETCURSEL, WM_COMMAND 


CBN_SELENDCANCEL ran] 


Parameters | 


Comments | 


| See Also 


The CBN_SELENDCANCEL notification message is sent when the user clicks an 
item and then clicks another window or control to hide the list box of a combo 
box. This notification message is sent before the CBN_CLOSEUP notification — 
message to indicate that the user’s selection should be ignored. 


wParam ; | | 
Specifies the identifier of the combo box. | 
[Param | 


Specifies the handle of the combo box in the low-order word, and specifies the 
_ CBN_SELENDCANCEL notification message in the high-order word. 


The CBN_SELENDCANCEL or CBN_SELENDOK notification message is sent 
even if the CBN_CLOSEUP notification message is not sent (as in the case of a 
combo box with the CBS_SIMPLE style). 


CBN_SELENDOK, WM_COMMAND 


CBN. SELENDOK : ee 


The CBN_SELENDOK notification message is sent when the user selects an 
item and then either presses the ENTER key or clicks the DOWN ARROW key to 
hide the list box of a combo box. This notification message is sent before the 


-CBN_CLOSEUP notification message to indicate that the user’s selection should 


be considered valid. 
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Parameters wParam 
Specifies the identifier of the combo box. 
lParam 


Specifies the handle of the combo box in the low-order word, and specifies the 
CBN_SELENDOK notification message in the high-order word. 


Comments The CBN_SELENDOK or CBN_SELENDCANCEL notification message is sent 
even if the CBN_CLOSEUP notification message is not sent (as in the case of a 
combo box with the CBS_SIMPLE style). 


See Also CBN_SELENDCANCEL, WM_COMMAND 


CBN_SETFOCUS lex 


The CBN_SETFOCUS notification message is sent when a combo box receives 
the input focus. The parent window of the combo box receives this notification 
message through a WM_COMMAND message. 


Parameters wParam | 
Specifies the identifier of the combo box. 
lParam 


Specifies the handle of the combo er in the low-order word, and specifies the 
CBN_SETFOCUS notification message in the high-order word. 


See Also  CBN_KILLFOCUS, WM_COMMAND 


EN_CHANGE fied tha og 


The EN_CHANGE notification message is sent when the user has taken an action 
that may have altered text in an edit control. Unlike the EN_UPDATE notification 
-message, this notification message is sent after Windows updates the display. The 
control’s parent window receives this notification message through a 
WM ~COMMAND message. 


Parameters wParam 
Specifies the identifier of the edit control. 


EN_HSCROLL 221 


lParam 
Specifies the handle of the edit control in the low-order word, and specifies the 
EN_CHANGE notification message in the high-order word. 


See Also EN_UPDATE, WM_COMMAND 


EN_ERRSPACE = ay 


The EN_ERRSPACE notification message is sent when an edit control cannot allo- 
cate enough memory to meet a specific request. The control’s parent window re- 
ceives this notification message through a WM_COMMAND message. 


Parameters — wParam 
_ Specifies the identifier of the edit control. 


[Param 
Specifies the handle of the edit control in the low-order word, and specifies the 
EN_ERRSPACE notification message in the high-order word. 


See Also WM _ COMMAND 


EN_HSCROLL 7 [2x | 
EN_HSCROLL 


_ The EN_HSCROLL notification message is sent when the user clicks an edit con- 
trol’s horizontal scroll bar. The control’s parent window receives this notification 
message through a WM_COMMAND message. The parent window is a . 
before the screen is updated. 


Parameters ~ wParam 
Specifies the identifier of the edit control. 


lParam © 
Specifies the handle of the edit control in the low- order word, and specifies the 
EN_HSCROLL notification message in the high-order word. 


See Also -EN_VSCROLL, WM_COMMAND 
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EN_KILLFOCUS — aos (ax 


The EN_KILLFOCUS notification message is sent when an edit control loses the 
input focus. The control’s parent window receives this notification message 
through a WM_COMMAND message. 


Parameters | wParam 
Specifies the identifier of the edit control. 
[Param 


Specifies the handle of the edit control in the low-order word, and specifies the 
EN_KILLFOCUS notification message in the high-order word. 


See Also EN_SETFOCUS, WM_COMMAND 


EN MAXTEXT 


The EN_MAXTEXT notification message is sent when the current insertion has 
exceeded the specified number of characters for the edit control. The insertion has 
been truncated. 


This message is also sent when an edit control does not have the 
ES_AUTOHSCROLL style and the number of characters to be inserted 
would exceed the width of the edit control. 


This message is also sent when an edit control does not have the 
ES_AUTOVSCROLL style and the total number of lines resulting from 
a text insertion would exceed the height of the edit control. 


The control’s parent window receives this notification message through a 
WM. COMMAND message. 


Parameters wParam 
Specifies the identifier of the edit control. 


[Param 
Specifies the handle of the edit control in the low- oder word, and specifies the — 
EN_ MAXTEXT notification message in the ree -order word. 


See Also EM_LIMITTEXT, WM_COMMAND 


EN_ UPDATE 223 


EN_SETFOCUS El 


Parameters 


See Also 


EN_UPDATE 


Parameters 


| See Also 


EN_SETFOCUS 


The EN_SETFOCUS notification message is sent when an edit control receives 
the input focus. The control’s parent window receives this notification message 
through a WM_COMMAND message. 


wParam 
Specifies the identifier of the edit control. 


lParam | 
Specifies the handle of the edit control in the low-order word, and specifies the 
EN_SETFOCUS notification message in the high-order word. 


-EN_KILLFOCUS, WM_COMMAND 


[ 2x | 


EN_UPDATE 


The EN_UPDATE notification message is sent when an edit control is about to 
screen altered text. This notification is sent after the control has formatted the text 
but before it screens the text. This makes it possible to alter the window size, if 
necessary. The control’s parent window receives this notification message through 
a WM_COMMAND message. 


wParam 
Specifies the identifier of the edit control. 


lParam | | | 
Specifies the handle of the edit control in the low-order word, and specifies the 
EN_UPDATE notification message in the high-order word. 


EN_CHANGE, WM_COMMAND 
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EN_VSCROLL 7) aa 


EN_VSCROLL 


The EN_VSCROLL notification message is sent when the user clicks an edit con- 
trol’s vertical scroll bar. The control’s parent window receives this notification 
message through aWM_COMMAND message. The parent window is notified 
before the screen is updated. 


Parameters wParam 
Specifies the identifier of the edit control. 


[Param : 
Specifies the handle of the edit control in the low-order word, and specifies the 
EN_VSCROLL notification message in the high-order word. 


See Also EN_HSCROLL, WM_COMMAND 


LBN_DBLCLK oe [ex] 


LBN_DBLCLK 


The LBN_DBLCLK notification message is sent when the user double-clicks a 
string in a list box. The parent window of the list box receives this notification 
message through a WM_COMMAND message. 


Parameters wParam 
Specifies the identifier of the list box. 


[Param | 
Specifies the handle of the list box in the low-order word, and specifies the 
~ LBN_DBLCLK notification message in the high-order word. 
Comments Only a list box that has LBS_NOTIFY style will send this notification message. 


See Also LBN_SELCHANGE, WM_COMMAND 


LBN_KILLFOCUS 225 


LBN_ERRSPACE nat Pie, aes 


LBN_ERRSPACE 


The LBN_ERRSPACE notification message is sent when a list box cannot allo- 
cate enough memory to meet a specific request. The parent window of the list box 
receives this notification message through a WM_COMMAND message. 


Parameters wParam 
Specifies the identifier of the list box. 


[Param | 
Specifies the handle of the list box in the low-order word, and specifies the 
LBN_ERRSPACE notification message in the hi gh-order word. 


See Also WM_COMMAND 


LBN_KILLFOCUS eee cr tet 


The LBN_KILLFOCUS notification message is sent when a list box loses the | 
input focus. The parent window of the list box receives _ snotnieation message 
through aWM_COMMAND message. 


Parameters wParam — 
| Specifies the identifier of the list box. 


lParam | 
Specifies the handle of the list box in the low-order word, and specifies the 
LBN_KILLFOCUS notification message in the high-order word. 


See Also LBN_SETFOCUS, WM_COMMAND 


226 LBN_SELCANCEL 


LBN_SELCANCEL — ar 


LBN_SELCANCEL 


The LBN_SELCANCEL notification message is sent when the user cancels the 
selection in a list box. The parent window of the list box receives this notification 
message through a WM_COMMAND message. 


Parameters wParam 
Specifies the identifier of the list box. 


[Param 
Specifies the handle of the list box in the low-order word, and specifies the 
LBN_SELCANCEL notification message in the high-order word. 


Comments This notification applies only to a list box that has the LBS_NOTIFY style. 


See Also | LBN_DBLCLK, LBN_SELCHANGE, LB_SETCURSEL, WM_COMMAND 


LBN_SELCHANGE ry 


LBN_ SELCHANGE 


The LBN_SELCHANGE notification message is sent when the selection in a list 
box is about to change. The parent window of the list box receives this notification 
message through a WM COMMAND message. , 


Parameters = wParam 
Specifies the identifier of the list box. 


[Param | 
Specifies the handle of the list box in the low-order word, and specifies the 
LBN_SELCHANGE notification message in the high-order word. 


Comments This notification is not sent if the selection is changed by the LB_SETCURSEL 
message. 


This notification applies only to a list box that has the LBS_NOTIFY style. 


The LBN_SELCHANGE notification is sent for a multiple-selection list box when- 
ever the user presses an arrow key, even if the selection does not change. 


See Also LBN_DBLCLK, LBN_SELCANCEL, LB_SETCURSEL, WM_COMMAND 


LBN_SETFOCUS 227 


LBN_SETFOCUS | 


The LBN_SETFOCUS notification message is sent when a list box receives the 
_ input focus. The parent window of the list box receives this notification message 
through a WM_COMMAND message. 


Parameters wParam | 
Specifies the identifier of the list box. 


[Param 
Specifies the handle of the list box in the low-order word, and specifies the 
LBN_SETFOCUS notification message in the high-order word. 


See Also | LBN_KILLFOCUS, WM_COMMAND 


Structures 


Alphabetic Reference 


— Chapter 3 


ABC 


Members 


Comments 


See Also 


ABC 231 


This chapter defines the sizes and meanings of the structures associated with func- 
tions for the Microsoft Windows operating system, version 3.1. | 


Following are the Windows structures, in alphabetic order. 


typedef struct tagABC { /* abc */ 


int abcA; 
UINT abcB; 
int abcC; 

} ABC; 


The ABC structure contains the width of a character in a TrueType font. 


abcA | 
Specifies the “A” spacing of the character. A spacing is the distance to add to 
the current position before drawing the character glyph. 


-abcB 


Specifies the “B” spacing of the character. B spacing is the width of me drawn 
portion of the character glyph. 


-—abcC 


Specifies the “C” spacing of ie character. C spacing is the distance to add to 
the current position to provide white space to the right of the character glyph. 


The total width of a character is the sum of the A, B, and C spaces. Either the A or 


the C space can be negative, to indicate underhangs or overhangs. 


GetCharABC Widths 
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BITMAP 


Members 


Comments 


typedef struct tagBITMAP { /* bm */ 


int bmType; 

int bmWidth; 

int bmHeight; 

int bmWidthBytes; 


BYTE bmPlanes; 
BYTE bmBitsPixel; 
void FAR* bmBits; 

} BITMAP; 


The BITMAP structure defines the height, width, color format, and bit values of a 
logical bitmap. 


bmType 
Specifies the bitmap type. For logical bitmaps, this member must be zero. 
bm Width 
Specifies the width of the bitmap, i in pixels. The width must be greater than 
zero. 


bmHeight | : 
Specifies the height of the a in raster lines. The height must be greater 
than zero. 


bm WidthBytes 
Specifies the number of bytes in each raster line. This value must be an 
even number since graphics device interface (GDI) assumes that the bit 
values of a bitmap form an array of integer (two-byte) values. In other words, 
bmWidthBytes * 8 must be the next multiple of 16 greater than or equal to the 
value obtained when the bm Width member is multiplied by the bmBitsPixel 
member. 


bmPlanes 
Specifies the number of color planes in the bitmap. 


bmBitsPixel 
Specifies the number of adjacent color bits on each plane needed to define a 
pixel. 

bmBits 
Points to the location of the bit values for the bitmap. The bmBits member 
must be a long pointer to an array of one-byte values. 


The currently used bitmap formats are monochrome and color. The monochrome 
bitmap uses a one-bit, one-plane format. Each scan is a multiple of 16 bits. 


See Also 
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Scans are organized as follows for a monochrome bitmap of height n: 


Scan @ 
Scan 1 


The pixels on a monochrome device are either black or white. If the corresponding 
bit in the bitmap is 1, the pixel is turned on (white). If the corresponding bit in the 
bitmap is zero, the pixel is turned off (black). 


All devices support bitmaps that have the RC_BITBLT bit set in the 
RASTERCAPS index of the GetDeviceCaps function. 


Each device has its own unique color format. In order to transfer a bitmap from 
one device to another, use the GetDIBits and SetDIBits functions. 


CreateBitmapIndirect, GetDIBits, GetObject, SetDIBits 


BITMAPCOREHEADER ae 


Members 


typedef struct tagBITMAPCOREHEADER { /* bmch */ 
DWORD. bcSize; 
— short  bcWidth; 
Short bcHeight; 
WORD bcPlanes; 
WORD bcBitCount; 
} BITMAPCOREHEADER; 


The BITMAPCOREHEADER structure contains information about the 
dimensions and color format of a device-independent bitmap (DIB). Windows ap- 
plications should use the BITMAPINFOHEADER structure instead of BITMAP- 
COREHEADER whenever possible. 


beSize | 
Specifies the number of bytes required by the BITMAPCOREHEADER 
structure. | | 
bceWidth | 
Specifies the width of the bitmap, in pixels. — 


_ beHeight 


Specifies the height of the bitmap, in pixels. , 
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bePlanes | 
Specifies the number of planes for the target device. This member must be set 
to 1. 


bcBitCount 
Specifies the number of bits per pixel. This value must be 1, 4, 8, or 24. 


Comments The BITMAPCOREINFO structure combines the BITMAPCOREHEADER 
structure and a color table to provide a complete definition of the dimensions and 
colors of a DIB. See the description of the BITMAPCOREINFO structure for 
more information about specifying a DIB. 


An application should use the information stored in the beSize member to locate 
the color table in a BITMAPCOREINFO structure with a method such as the fol- 
lowing: 


pColor = ((LPSTR) pBitmapCoreInfo + (WORD) (pBitmapCoreInfo -> bcSize)) 


See Also BITMAPCOREINFO, BITMAPINFOHEADER, BITMAPINFOHEADER 


BITMAPCOREINFO — 


typedef: struct tagBITMAPCOREINFO { /* bmci */ | 
BITMAPCOREHEADER bmciHeader; 
RGBTRIPLE bmciColors[1]; 

} BITMAPCOREINFO; 


The BITMAPCOREINFO structure fully defines the dimensions and color infor- 
mation for a device-independent bitmap (DIB). Windows applications should use 
the BITMAPINFO structure instead of BITMAPCOREINFO whenever 
possible. 


Members _ bmciHeader 
Specifies a BITMAPCOREHEADER structure that contains information 
about the dimensions and color format of a DIB. 


bmciColors 
_ Specifies an array of RGBTRIPLE structures that define the colors in the bit- 
map. 


Comments The BITMAPCOREINFO structure describes the dimensions and colors of a bit- 
map. It is followed immediately in memory by an array of bytes which define the 
pixels of the bitmap. The bits in the array are packed together, but each scan line 


See Also 
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must be zero-padded to end on a LONG boundary. Segment boundaries, however, 
can appear anywhere in the bitmap. The origin of the bitmap is the lower-left 
corner. | 


The bcBitCount member of the BITMAPCOREHEADER structure determines 
the number of bits that define each pixel and the maximum number of colors in the 
bitmap. This member may be set to any of the following values: 


Value Meaning 


1 The bitmap is monochrome, and the bmciColors member must contain two | 
entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the 
pixel is displayed with the color of the first entry in the bmciColors table. 

If the bit is set, the pixel has the color of the second entry in the table. 


4 The bitmap has a maximum of 16 colors, and the bmciColors member con- 
tains 16 entries. Each pixel in the bitmap is represented by a four-bit index 
into the color table. 

For example, if the first byte in the bitmap is Ox1F, the byte represents two 
pixels. The first pixel contains the color in the second table entry, and the 
second pixel contains the color in the sixteenth table entry. 


8 The bitmap has a maximum of 256 colors, and the bmciColors member 
contains 256 entries. In this case, each byte in the array represents a single 
pixel. : 

24 The bitmap has a maximum of 2” colors. The bmciColors member is 


NULL, and each 3-byte sequence in the bitmap array represents the relative. 
intensities of red, green, and blue, respectively, of a pixel. | 


The colors in the bmciColors table should appear in order of importance. 


Alternatively, for functions that use DIBs, the bmciColors member can be an 
array of 16-bit unsigned integers that specify an index into the currently realized 
logical palette instead of explicit RGB values. In this case, an application 

using the bitmap must call DIB functions with the wUsage parameter set to. 
DIB_PAL_COLORS. | 


Note The bmciColors member should not contain palette indexes if the bitmap is 
to be stored in a file or transferred to another application. Unless the application 
uses the bitmap exclusively and under its complete control, the bitmap color table 
should contain explicit RGB values. 


BITMAPINFO, BITMAPCOREHEADER, RGBTRIPLE 
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BITMAPFILEHEADER 


BITMAPFILEHEADER a . 


typedef struct tagBITMAPFILEHEADER { /* bmfh */ 
UINT _bfType; 
DWORD bfSize; 
UINT bfReservedl1; 
UINT bfReserved2; 
DWORD bfOffBits; 
} BITMAPFILEHEADER; 


The BITMAPFILEHEADER structure contains information about the type, size, 
and layout of a device-independent bitmap (DIB) file. 


Members bfType 


Specifies the type of file. This member must be BM. 


bfSize 
Specifies the size of the file, in bytes. 


bfReserved1 | 
Reserved; must be set to zero. 


bfReserved2 
Reserved; must be set to zero. 


bfOffBits 
Specifies the byte offset from the BITMAPFILEHEADER structure to the 
actual bitmap data in the file. 


Comments A BITMAPINFO or BITMAPCOREINEO structure immediately follows the 


See Also 


BITMAPFILEHEADER structure in the DIB file. 


BITMAPCOREINFO, BITMAPINFO 


BITMAPINFO 


typedef struct tagBITMAPINFO { /* bmi */ 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD ~bmiColors[1]; 

} BITMAPINFO; 


The BITMAPINFO structure fully defines the dimensions and color information 
for a Windows 3.0 or later device-independent bitmap (DIB). 


Members 


Comments 
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bmiHeader | 
Specifies a BITMAPINFOHEADER structure that contains information about 
the dimensions and color format of a DIB. 


bmiColors eos 
Specifies an array of RGBQUAD structures that define the colors in the bitmap. 


A Windows 3.0 or later DIB consists of two distinct parts: a BITMAPINFO struc- 
ture, which describes the dimensions and colors of the bitmap, and an array of 
bytes defining the pixels of the bitmap. The bits in the array are packed together, 
but each scan line must be zero-padded to end on a LONG boundary. Segment 
boundaries, however, can appear anywhere in the bitmap. The origin of the bitmap 
is the lower-left corner. 


The biBitCount member of the BITMAPINFOHEADER structure determines 
the number of bits which define each pixel and the maximum number of colors in 
the bitmap. This member may be set to any of the following values: 


Value Meaning 


1 The bitmap is monochrome, and the bmciColors member must contain two 
entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the 
pixel is displayed with the color of the first entry in the bmciColors table. 
If the bit is set, the pixel has the color of the second entry in the table. 


4 The bitmap has a maximum of 16 colors, and the bmciColors member con- 
tains 16 entries. Each pixel in the bitmap is represented by a four-bit index 
into the color table. 


For example, if the first byte in the bitmap is Ox1F, the byte represents two 


pixels. The first pixel contains the color in the second table entry, and the 
second pixel contains the color in the sixteenth table entry. 


8 | The bitmap has a maximum of 256 colors, and the bmciColors member 
contains 256 entries. In this case, each byte in the array represents a single 
pixel. 

24 The bitmap has a maximum of 2” colors. The bmciColors member is 


NULL, and each 3-byte sequence in the bitmap array represents the relative 
intensities of red, green, and blue, respectively, of a pixel. 


The biClrUsed member of the BITMAPINFOHEADER structure specifies the 
number of color indexes in the color table actually used by the bitmap. If the 
biClrUsed member is set to zero, the bitmap uses the maximum number of colors 
corresponding to the value of the biBitCount member. 


The colors in the bmiColors table should appear in order of importance. 


Alternatively, for functions that use DIBs, the bmiColors member can be an array 
of 16-bit unsigned integers that specify an index into the currently realized logical 
palette instead of explicit RGB values. In this case, an application using the 
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See Also 


bitmap must call DIB functions with the wUsage pram set to 
DIB_PAL_COLORS. 


Note The bmiColors member should not contain palette indexes if the bitmap is 
to be stored in a file or transferred to another application. Unless the application 
uses the bitmap exclusively and under its complete control, the bitmap color table 
should contain explicit RGB values. 
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Members 


typedef struct tagBITMAPINFOHEADER { /* bmih */ 
DWORD biSize; 
LONG biWidth; 
~ LONG biHeight; 
~ WORD biPlanes; 
WORD biBitCount; 
DWORD biCompression; 
DWORD  biSizeImage; 
LONG biXPelsPerMeter; 
LONG biYPelsPerMeter; 
DWORD biClrUsed; 
DWORD biClIrImportant; 
} BITMAPINFOHEADER; 


The BITMAPINFOHEADER structure contains information about the dimen- 
sions and color format of a Windows 3.0 or later device-independent bitmap 
(DIB). 


biSize | 
Specifies the number of bytes required by the BITMAPINFOHEADER 
structure. 


- piWidth 


| Specifies the width of the bitmap, in pixels. 


biHeight 
Specifies the baci of the ee in pixels. 


biPlanes 
Specifies the number of planes for the target device. This member must be set 
to 1. | | 


biBitCount 
Specifies the number of bits per pixel. This value must be 1, 4, 8, or 24. 
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biCompression 
Specifies the type of compression for a songieeeed bitmap. It can be one of the 
following values: 


Value Meaning 


BI_RGB | Specifies that the bitmap is not compressed. 

BI_RLE8 Specifies a run-length encoded format for bitmaps with 8 bits per 
pixel. The compression format is a 2-byte format consisting of a count 
byte followed by a byte containing a color index. For more informa- 
tion, see the following Comments section. 

BI_RLE4 Specifies a run-length encoded format for bitmaps with 4 bits per 
pixel. The compression format is a 2-byte format consisting of a count 
byte followed by two word-length color indexes. For more informa- 
tion, see the following Comments section. 


biSizeImage 
Specifies the size, in bytes, of the image. It is valid to set this member to zero if 
the bitmap is in the BI_LRGB format. 


biXPelsPerMeter | 
Specifies the horizontal resolution, in pixels per meter, of the target device for 
the bitmap. An application can use this value to select a bitmap from a resource 
group that best matches the characteristics of the current device. 


biYPelsPerMeter 
Specifies the vertical resolution, in pixels per meter, of the target device for the 
bitmap. 


biClrUsed 
Specifies the number of color fence in the color table actually used by the bit-_ 
map. If this value is zero, the bitmap uses the maximum number of colors corre- 
sponding to the value of the biBitCount member. For more information on the 
maximum sizes of the color table, see the description of the BITMAPINFO 
structure earlier in this chapter. 


If the biClrUsed member is nonzero, it specifies the actual number of colors 
that the graphics engine or device driver will access if the biBitCount member 
is less than 24. If biBitCount is set to 24, biClrUsed specifies the size of the 
reference color table used to optimize performance of Windows color palettes. 


_ If the bitmap is a packed bitmap (that is, a bitmap in which the bitmap array im- 
mediately follows the BITMAPINFO header and which is referenced by a 
single pointer), the biClrUsed member must be set to zero or to the actual size 
of the color table. 


biClrImportant 
Specifies the number of color indexes that are considered important for display- 
ing the bitmap. If this value is zero, all colors are important. | 
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Comments 


The BITMAPINFO structure combines the BITMAPINFOHEADER structure 
and a color table to provide a complete definition of the dimensions and colors of 
a Windows 3.0 or later DIB. For more information about specifying a Windows 
3.0 DIB, see the description of the BITMAPINFO structure. 


An application should use the information stored in the biSize member to locate 
the color table in a BITMAPINFO structure as follows: 


pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo->bmiHeader.biSize) ) 


Windows supports formats for compressing bitmaps that define their colors with 8 
bits per pixel and with 4 bits per pixel. Compression reduces the disk and memory 
storage required for the bitmap. The following paragraphs describe these formats. 


BI_RLE8 When the biCompression member is set to BI_LRLE8, the bitmap is 
compressed using a run-length encoding format for an 8-bit bitmap. This format 
may be compressed in either of two modes: encoded and absolute. Both modes 
can occur anywhere throughout a single bitmap. 


Encoded mode consists of two bytes: the first byte specifies the number of con- 
secutive pixels to be drawn using the color index contained in the second byte. In 
addition, the first byte of the pair can be set to zero to indicate an escape that 
denotes an end of line, end of bitmap, or a delta. The interpretation of the escape 
depends on the value of the second byte of the pair. The following list shows the 
meaning of the second byte: 


Value Meaning 
0 End of line. 
1 : End of bitmap. 
i: Delta. The two bytes following the escape contain unsigned values indicat- 


ing the horizontal and vertical offset of the next pixel from the current posi- 
tion. 


Absolute mode is signaled by the first byte set to zero and the second byte set to a 
value between 0x03 and OxFF. In absolute mode, the second byte represents the 


number of bytes that follow, each of which contains the color index of a single 


pixel. When the second byte is set to 2 or less, the escape has the same meaning as 


in encoded mode. In absolute mode, each run must be aligned on a word boundary. 


The following example shows the hexadecimal values of an 8-bit compressed bit- 
map: , Po | 


Q@3 @4 @5 06 @@ 03 45 56 67 0@ 02 78 0@ 02 O5 a1 
02 78 00 0@ 09 1E 00 01 7 


This bitmap would expand as follows (two-digit values represent a color index for 
a single pixel): | 


See Also 
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04 04 04 

06 06 06 06 06 

45 56 67 

78 78 

move current position 5 right and 1 down 
78 78 

end of line 

1E 1E 1E 1E 1E 1E 1E 1E 1E 

end of RLE bitmap. 


BI_RLE4 When the biCompression member is set to BI_LRLE4, the bitmap is 
compressed using a run-length encoding (RLE) format for a 4-bit bitmap, which 


also uses encoded and absolute modes. In encoded mode, the first byte of the pair 


contains the number of pixels to be drawn using the color indexes in the second 
byte. The second byte contains two color indexes, one in its high-order nibble (that 
is, its low-order four bits) and one in its low-order nibble. The first of the pixels is 
drawn using the color specified by the high-order nibble, the second is drawn 
using the color in the low-order nibble, the third is drawn with the color in the 
high-order nibble, and so on, until all the ee specified by the first byte have 
been drawn. 


In absolute mode, the first byte contains zero, the coud byte contains the number 
of color indexes that follow, and subsequent bytes contain color indexes in their _ 
high- and low-order nibbles, one color index for each pixel. In absolute mode, 
each run must be aligned on a word boundary. The end-of-line, end-of-bitmap, and , 
delta escapes also apply to BI_LRLE4. 


The following example shows the hexadecimal values of a 4-bit compressed bit- 
map: | 


Q@3 04 05 06 0@ 06 45 56 67 00 04 78 00 02 05 21 
04 78 08 00 09 1E 00 O1 


This bitmap would expand as follows (single-digit values represent a color index 


_ for a single pixel): 


0 4 Q 

060680 

455667 

7: Bde Bee 2 : 
move current position 5 right and 1 down 
787 8 7 
end of line 

LE LE LE: 1 E-1 


end of RLE bitmap 
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CBT_CREATEWND 


Members 


See Also 


CBTACTIVATESTRUCT 


Members 


See Also 


typedef struct tagCBT_CREATEWND { /* cbtcw */ 
CREATESTRUCT FAR* lpcs; 
HWND hwndInsertAfter; 

} CBT_CREATEWND; 7 


The CBT_CREATEWND structure contains information passed to a WH_CBT 
hook function before a window is created. 


Ipcs 
Points to a CREATESTRUCT structure that contains initialization parameters 
for the window about to be created. 


hwndInsertAfter 
Identifies a window in the window manager’s list that will precede the window 
being created. If this parameter is NULL, the window being created is the top- 
most window. If this parameter is 1, the window being created is the bottom- 
most window. 


CBTProc, SetWindowsHook 


typedef struct tagCBTACTIVATESTRUCT { /* cas */ 
BOOL fMouse; | 
HWND hWndActive; 

} CBTACTIVATESTRUCT; 


The CBTACTIVATESTRUCT structure contains information passed toa 
WH_CBT hook function before a window is activated. 


fMouse 
Specifies whether the window is being activated as a result of a mouse click. 
This value is nonzero if a mouse click is causing the activation. Otherwise, this 
value is zero. 


- hWndActive 


Identifies the currently active window. 


SetWindowsHook 
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CHOOSECOLOR a] 


Members 


#Finclude <commd1g.h> 


typedef struct tagCHOOSECOLOR { /* cc */ 
DWORD 1StructSize; | 
HWND hwndOwner; 
HWND hInstance; 
COLORREF rgbResult; 
- COLORREF FAR* IpCustColors; 
DWORD Flags; 
LPARAM 1CustData; | 
~ UINT (CALLBACK* IpfnHook)(HWND, UINT, WPARAM, LPARAM); 
LPCSTR' IpTemplateName; 
} CHOOSECOLOR; 


The CHOOSECOLOR structure contains information that the system uses to ini- 
tialize the system-defined Color dialog box. After the user chooses the OK button 
to close the dialog box, the system returns information about the user’s selection 
in this structure. 


IStructSize 
Specifies the length of the structure, in bytes. This member is filled on input. 


~ hwndOwner 


Identifies the window that c owns the dialog box. This member can be any valid 
window handle, or it should be NULL if the dialog box is to have no owner. 


_ If the CC_LSHOWHELFP flag is set, hwndOwner must identify the window that 
owns the dialog box. The window procedure for this owner window receives a 
notification message when the user chooses the Help button. (The identifier for 
the notification message is the value returned by the RegisterWindowMessage 
function when HELPMSGSTRING is passed as its argument. ys 


This member is filled on input. 


hInstance 
Identifies a data block that contains the dialog box template specified by the 
IpTemplateName member. This member is used only if the Flags member | 
specifies the CC_ENABLETEMPLATE or 
CC_ENABLETEMPLATEHANDLE flag; otherwise, this member is ignored. 
‘This member is filled on input. 


rgbResult 
Specifies the color that is initially selected when the dialog box is displayed, 
and specifies the user’s color selection after the user has chosen the OK button 
— to close dialog box. If the CC_RGBINIT flag is set in the Flags member before 
_ the dialog box is displayed and the value of this member is not among the 
colors available, the system selects the nearest solid color available. If this 
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member is NULL, the first selected color is black. This member is filled on 
input and output. | 


IpCustColors 
Points to an array of 16 doubleword values, each of which specifies the intensi- 
ties of the red, green, and blue (RGB) components of a custom color box in the 
dialog box. If the user modifies a color, the system updates the array with the 
new RGB values. This member is filled on input and output. 


Flags 
_ Specifies the dialog box initialization flags. This member may be a combination 
of the following values: 


Value Meaning 

CC_ENABLEHOOK _ Enables the hook function specified in the 
IpfnHook member. 

CC_ENABLETEMPLATE Causes the system to use the dialog box 


template identified by the hInstance 
member and pointed to by the 
IpTemplateName member. 


CC_ENABLETEMPLATEHANDLE Indicates that the hInstance member iden- 
tifies a data block that contains a pre- 
loaded dialog box template. If this flag is 
specified, the system ignores the 
IpTemplateName member. 


CC_FULLOPEN Causes the entire dialog box to appear 
when the dialog box is displayed, includ- 
ing the portion that allows the user to 
create custom colors. Without this flag, 
the user must select the Define Custom 
Color button to see that portion of the 
dialog box. | 

CC_PREVENTFULLOPEN Disables the Define Custom Colors 
button, preventing the user from creating 
custom colors. 

CC_RGBINIT Causes the dialog box to use the color 
specified in the rgbResult member as the 
initial color selection. 

CC_SHOWHELP Causes the dialog box to show the Help 
button. If this flag is specified, the _ 
hwndOwner member must not be NULL. 


These flags are used when the structure is initialized. 


Comments 


See Also 
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ICustData 
Specifies application-defined data that the system passes to the hook 
function pointed to by the IpfnHook member. The system passes a pointer 
to the CHOOSECOLOR structure in the /Param parameter of the 
WM_INITDIALOG message; this pointer can be used to retrieve the 
ICustData member. 


IpfnHook 

Points to a hook function that processes messages intended for the 
dialog box. To enable the hook function, an application must specify the 
CC_ENABLEHOOK value in the Flags member; otherwise, the system ignores 
this structure member. The hook function must return zero to pass a message 
that it didn’t process back to the dialog box procedure in COMMDLG.DLL. 

The hook function must return a nonzero value to prevent the dialog box proce- 
dure in COMMDLG.DLL from processing a message it has already processed. 
This member is filled on input. 


IpTemplateName 
Points to a null-terminated string that specifies the name of the resource file for 
the dialog box template that is to be substituted for the dialog box template in 
COMMDLG.DLL. An application can use the MAKEINTRESOURCE macro 
for numbered dialog box resources. This member is used only if the Flags mem- 
ber specifies the CCLENABLETEMPLATE flag; otherwise, this member is ig- _ 
nored. This member i is filled on ‘input. , 


Some members of this structure are filled only when the dialog box is created, and 
some have an initialization value that changes when the user closes the dialog box. 
Whenever a description in the Members section does not specify how the value of 


a member is assigned, the value is assigned only when the dialog box is created. 


ChooseColor 
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CHOOSEFONT 


Members 


dFinclude <commdlg.h> 


typedef struct tagCHOOSEFONT { /* cf */ 


DWORD 1StructSize; 
HWND hwndOwner; 

HDC hDC; 

LOGFONT FAR* |pLogFont; 

int iPointSize; 
DWORD , Flags; 

COLORREF rgbColors; 
LPARAM 1CustData; 

UINT (CALLBACK* ITpfnHook)(HWND, UINT, WPARAM, LPARAM) ; 
LPCSTR lTpTemplateName; . 
HINSTANCE hInstance; 

LPSTR lpszStyle; 

UINT nFontType; 

int nSizeMin; 

int nSizeMax; 


} CHOOSEFONT; 


The CHOOSEFONT structure contains information that the system uses to initial- 
ize the system-defined Font dialog box. After the user chooses the OK button to 
close the dialog box, the system returns information about the user’s selection in 
this structure. | 


IStructSize 
Specifies the length of the structure, in bytes. This member is filled on input. 


hwndOwner 
Identifies the window that owns the dialog box. This member can be any valid 
window handle, or it should be NULL if the dialog box is to have no owner. 


If the CF_SHOWHELP flag is set, hwndOwner must identify the window that 
owns the dialog box. The window procedure for this owner window receives a 
notification message when the user chooses the Help button. (The identifier for 
the notification message is the value returned by the RegisterWindowMessage 
function when HELPMSGSTRING is passed as its argument.) 


This member is filled on input. 


hDC 
Identifies either the device context or the information context of the printer for 
which fonts are to be listed in the dialog box. This member is used only if the 
Flags member specifies the CF_PRINTERFONTS flag; otherwise, this mem- 
ber is ignored. 


This member is filled on input. 


IpLogF ont | 
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Points to a LOGFONT structure. If an application initializes the 

members of this structure before calling ChooseF ont and sets the 
CF_INITTOLOGFONTSTRUCT flag, the ChooseFont function initializes 
the dialog box with the font that is the closest possible match. After the user 
chooses the OK button to close the dialog box, the ChooseF ont function sets 
the members of the LOGFONT structure based on the user’s final selection. 


This member is filled on input and output. 


iPointSize 


Specifies the size of the selected font, in tenths of a point. The ChooseFont 
function sets this value after the user chooses the OK button to close the dialog 


box. 
Flags 


Specifies the dialog box initialization flags. This member can 1 be a combination 


of the following values: 
Value 


CF_APPLY 


CF_ANSIONLY 


CF BOTH 


CF_TTONLY 


CF_EFFECTS 


Meaning | 
Specifies.that the ChooseF ont function 
should enable the Apply button. 


Specifies that the ChooseF ont function 
should limit font selection to those fonts 


that use the Windows character set. (If this 


flag is set, the user cannot select a font 
that contains only symbols.) 


Causes the dialog box to list the available 
printer and screen fonts. The hDC mem- — 
ber identifies either the device context or 
the information context associated with — 
the printer. 


Specifies that the ChooseF ont function 
should enumerate and allow the selection 
of only TrueType fonts. | 


Specifies that the ChooseF ont function 
should enable strikeout, underline, and 
color effects. If this flag is set, the | 
lfStrikeOut and IfUnderline members of 
the LOGFONT structure and the | 
rgbColors member of the 
CHOOSEFONT structure can be set 
before calling ChooseFont. And, if this 
flag is not set, the ChooseFont function — 
can set these members after the user — 


_ chooses the OK button to 0 close the 


dialog box. 
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Value 
CF_ENABLEHOOK 


CF_ENABLETEMPLATE 


CF_ENABLETEMPLATEHANDLE 


CF_FIXEDPITCHONLY 


CF_FORCEFONTEXIST 


CF_INITTOLOGFONTSTRUCT 


CF_LIMITSIZE 


CF_NOFACESEL 


CF_NOOEMFONTS 


CF_NOSIMULATIONS 


CF_NOSIZESEL 


CF_NOSTYLESEL 


Meaning 


Enables the hook function specified in the 
IpfnHook member of this structure. 


Indicates that the hInstance member 
identifies a data block that contains the 
dialog box template pointed to by 
IpTemplateName. | 


Indicates that the hInstance member 
identifies a data block that contains a pre- 
loaded dialog box template. If this flag is 
specified, the system ignores the 
IpTemplateName member. 


Specifies that the ChooseF ont function 
should select only monospace fonts. 


Specifies that the ChooseFont function 
should indicate an error condition if the 
user attempts to select a font or font style 
that does not exist. 


Specifies that the ChooseF ont function 
should use the LOGFONT structure 
pointed to by IpLogF ont to initialize the 
dialog box controls. 


Specifies that the ChooseF ont function 
should select only font sizes within the 
range specified by the nSizeMin and 
nSizeMax members. 


Specifies that there is no selection in the 
Font (face name) combo box. Applica- 
tions use this flag to support multiple font 
selections. This flag is set on input and 
output. 


Specifies that the ChooseFont function 
should not allow vector-font selections. 
This flag has the same value as 
CF_NOVECTORFONTS. 


Specifies that the ChooseF ont function 
should not allow graphics-device- 
interface (GDI) font simulations. 


Specifies that there is no selection in the 
Size combo box. Applications use this 
flag to support multiple size selections. 
This flag is set on input and output. 


Specifies that there is no selection in the 
Font Style combo box. Applications use 
this flag to support multiple style selec- 
tions. This flag is set on input and output. 
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Value > Meaning 


CF_NOVECTORFONTS Specifies that the ChooseF ont function 
should not allow vector-font selections. 
This flag has the same value as 
CF_NOOEMFONTS. 


CF_PRINTERFONTS Causes the dialog box to list only the fonts 
supported by the printer associated with 
the device context or information context 
that is identified by the hDC member. 


CF_SCALABLEONLY Specifies that the ChooseF ont function 
should allow the selection of only scalable 
fonts. (Scalable fonts include vector fonts, 
some printer fonts, TrueType fonts, and 
fonts that are scaled by eer algorithms 
or technologies.) 


CF_SCREENFONTS Causes the dialog box to list only the 
screen fonts supported by the system. 
CF_SHOWHELP | Causes the dialog box to show the Help 


button. If this option is specified, the 
hwndOwner must not be NULL. 


CF_USESTYLE | Specifies that the IpszStyle member 
points to a buffer that contains a style- 
description string that the ChooseFont 
function should use to initialize the Font — 
Style box. When the user chooses the OK 
button to close the dialog box, the 
ChooseF ont function copies the style 
description for the user’s selection to this 
buffer. | 

CF_WYSIWYG Specifies that the ChooseF ont function 
should allow the selection of only fonts 
that are available on both the printer and 
the screen. If this flag is set, the 
CF_BOTH and CF_SCALABLEONLY 
flags should also be set. 


These flags may be set when the structure is initialized, except where specified. 


rgbColors 
If the CF_EFFECTS flag is set, this member contains the red, green, and blue 
(RGB) values the ChooseF ont function should use to set the text color. After 
the user chooses the OK button to close the dialog box, this member contains 
the RGB values of the color the user selected. 


This member is filled on input and output. 
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ICustData | | 
Specifies application-defined data that the application passes to the hook func- 
tion. The system passes a pointer to the CHOOSEFONT data structure in the 
[Param parameter of the WM_INITDIALOG message; the l1CustData member 
can be retrieved using this pointer. 


IpfnHook 

Points to a hook function that processes messages intended for the 
dialog box. To enable the hook function, an application must specify the 

-CF_ENABLEHOOK value in the Flags member; otherwise, the system ignores 
this structure member. The hook function must return zero to pass a message 
that it didn’t process back to the dialog box procedure in COMMDLG.DLL. 
The hook function must return a nonzero value to prevent the dialog box proce- 
dure in COMMDLG.DLL from processing a message it has already processed. — 


This member is filled on input. 


IpTemplateName 
Points to a null- terminated string that specifies the name of the resource file for 
the dialog box template to be substituted for the dialog box template in 
COMMDLG.DLL. An application can use the MAKEINTRESOURCE macro 
for numbered dialog box resources. This member is used only if the Flags mem- 
ber specifies the CF_ ENABLETEMPLATE flag; otherwise, this member is ig- 
nored. 


This member is filled on input. 


hInstance | 
Identifies a data block that contains the dialog box template specified by the 
IpTemplateName member. This member is used only if the Flags member 
specifies the CF_ENABLETEMPLATE or the 
_CF_ENABLETEMPLATEHANDLE flag; otherwise, this member is ignored. 


This member is filled on input. 


IpszStyle 
Points to a buffer that contains a style-description string for the font. If the 
CF_USESTYLE flag is set, the ChooseFont function uses the data in this buff- 
er to initialize the Font Style box. When the user chooses the OK button to 
close the dialog box, the ChooseF ont function copies the string in the Font © 
Style box into this buffer. 


The buffer pointed to by IpszStyle must be at least LF_FACESIZE bytes long. 
This member is filled on input and output. — 
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nFontType 
Specifies the type of the selected font. This member can be one or more of the 
values in the following list: 


Value Meaning 


BOLD_FONTTYPE Specifies that the font is bold. This value applies 
only to TrueType fonts. This value corresponds to 
the value of the ntmF lags member of the 
NEWTEXTMETRIC structure. 


ITALIC_FONTTYPE Specifies that the font is italic. This value applies 
only to TrueType fonts. This value corresponds to 
the value of the ntmFlags member of the 


NEWTEXTMETRIC structure. | 
PRINTER_FONTTY PE Specifies that the font is a printer font. 
REGULAR_FONTTYPE Specifies that the font is neither bold nor italic. 


This value applies only to TrueType fonts. This 
value corresponds to the value of the ntmFlags 
member of the NEWTEXTMETRIC structure. 


SCREEN_FONTTYPE Specifies that the font is a screen font. 


SIMULATED_FONTTYPE Specifies that the font is simulated by GDI. This is 
not set if the CF_NOSIMULATIONS flag is set. 


nSizeMin | ; 
Specifies the minimum point size that a user can select. The ChooseFont func- 
tion will recognize this member only if the CF_LIMITSIZE flag is set. 


This member is filled on input. 


nSizeMax | | 
Specifies the maximum point size that a user can select. The ChooseF ont func- ~ 
tion will recognize this member only if the CF_LIMITSIZE flag is set. 


This member is filled on input. 


See Also ChooseFont 
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CLASSENTRY 


#include <toolhelp.h> 


typedef struct tagCLASSENTRY { /* ce */ 
DWORD dwSize; 
-HMODULE hInst; 
char szClassName[MAX_CLASSNAME + 1]; 
WORD . wNext; 

} CLASSENTRY; 


The CLASSENTRY structure contains the name of a Windows class and a near 
pointer to the next class in the list. For more information about Windows classes, 


— see the GetClassInfo function in the Microsoft Windows nO GE S 


Members 


See Also 


Reference, Volume 2. 


dwSize 
Specifies the size of the CLASSENTRY structure, in bytes. 


hInst 
Identifies the instance handle of the task that owns the class. An application 
needs this handle to call GetClassInfo. The hInst member is really a handle to 
a module, since Windows classes are owned by modules. Therefore, this hInst 
will not match the hInst passed as a parameter to the WinMain function of the 
owning task. 


szClassName 
Specifies the null-terminated string that contains the class name. An application 
needs this name to call Se 


wNext 
Specifies the next class in the list. This member is reserved for internal use by 
Windows. 


ClassFirst, ClassNext 
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CLIENTCREATESTRUCT 


Members 


See Also 


typedef struct tagCLIENTCREATESTRUCT { /* ccs */ 
HANDLE hWindowMenu; 
UINT idFirstChild; 

} CLIENTCREATESTRUCT; 


The CLIENTCREATESTRUCT structure contains information about the menu 
and first multiple document interface (MDI) child window of an MDI client win- 
dow. An application passes a long pointer to this structure as the JpParam parame- 
ter of the CreateWindow function when creating an MDI client window. 


hWindowMenu 
Identifies the menu handle of the application’s Window menu. An application 
_ can retrieve this handle from the menu of the MDI frame window by using the 
GetSubMenu function. 


idFirstChild 

Specifies the child window identifier of the first MDI child window created. 
Windows increments the identifier for each additional MDI child window that 
the application creates, and reassigns identifiers when the application destroys a 

- window to keep the range of identifiers continuous. These identifiers are used 
in WM_COMMAND messages to the application’s MDI frame window when a 
child window is selected from the Window menu; they should not conflict with 
any other command identifiers. 


CreateWindow, GetSubMenu 
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COMPAREITEMSTRUCT wae oh 


Members 


typedef struct tagCOMPAREITEMSTRUCT { /* cis */ 
UINT CtlType; ; 
UINT CtlID; 
HWND hwndItem; 
UINT itemID1; 
DWORD itemDatal; 
UINT itemID2; 
DWORD itemData2; 
} COMPAREITEMSTRUCT; 


The COMPAREITEMSTRUCT structure supplies the identifiers and applica- 
tion-supplied data for two items in a sorted owner-drawn combo box or list box. 


Whenever an application adds a new item to an owner-drawn combo or list box 
created with the CBS_SORT or LBS_SORT style, Windows sends the owner a 
WM_COMPAREITEM message. The /Param parameter of the message contains 
a long pointer to a COMPAREITEMSTRUCT structure. When the owner re- 
ceives the message, it compares the two items and returns a value indicating which 
item sorts before the other. For more information, see the description of the 


WM_COMPAREITEM message in Chapter 2, “Messages.” 


CtlType 
Specifies ODT_LISTBOX (which identifies an owner-drawn list box) or 
ODT_COMBOBOxX (which identifies an owner-drawn combo box). 


CuID 
Specifies the identifier of the list box or combo box. 


hwndItem 
Identifies the control. 


itemID1 
Specifies the index of the first item in the list box or r combo box being com- 
pared. 


itemDatal 
Specifies application-supplied data for the first item being compared. (This 
value was passed as the /Param parameter of the message that added the item to 
the combo box or list box.) _ | 


itemID2 


Specifies the index of the second item in the list box or combo box being com- 
pared. 


itemData2 
Specifies application-supplied data for the second item being compared. This 
value was passed as the /Param parameter of the message that added the item to 
the combo box or list box. 
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COMSTAT 34) 


typedef struct tagCOMSTAT { /* cmst 2 a / 
BYTE status; /* status of transmission * / 
UINT cbInQue; /* count of characters in Rx Queue */ 
UINT cbOutQue; /* count of characters in Tx Queue */ 
} COMSTAT; 


The COMSTAT structure contains information about a communications device. 


Members status | 
Specifies the status of the transmission. This member can be one or more of the 
following flags: 
Flag _ Meaning 
CSTF_CTSHOLD Specifies whether transmission is waiting for the CTS 


(clear-to-send) signal to be sent. 


CSTF_DSRHOLD Specifies whether transmission is waiting for the DSR 
(data-set-ready) signal to be sent. | 

CSTF_RLSDHOLD Specifies whether transmission is waiting for the RLSD 
(receive-line-signal-detect) signal to be sent. 

CSTF_XOFFHOLD Specifies whether transmission is waiting as a result of the 

| XOFF character being received. 
CSTF_XOFFSENT Specifies whether transmission is waiting as a result of the 
| | XOFF character being transmitted. Transmission halts 

when the XOFF character is transmitted and used by sys- 
tems that take the next character as XON, regardless of the 
actual character. | 


CSTF_EOF Specifies whether the end-of-file (EOF) character has been 
received. 
CSTF_TXIM Specifies whether a character is waiting to be transmitted. 
cbInQue 
Specifies the number of characters in the receive queue. 
cbOutQue 


Specifies the number of characters in the transmit queue. 


See Also | GetCommError 
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CONVCONTEXT 


Members 


See Also 


#Finclude <ddem].h> 


— typedef struct tagCONVCONTEXT { /* cc * / 


UINT cb; 

UINT wFlags; 
UINT wCountryID; 
int iCodePage; 
DWORD dwLangID; 
DWORD dwSecurity; 


} CONVCONTEXT; 


The CONVCONTEXT structure contains information that makes it possible for 
applications to share data in several different languages. 


cb | 
Specifies the size, in bytes, of the CONVCONTEXT structure. 


wFlags 
Specifies conversation-context flags. Currently, no flags are defined for this 
member. 


wCountryID 
Specifies the country-code identifier for topic-name and item-name strings. 


iCodePage 
Specifies the code page for topic-name and item-name strings. Unilingual 
clients should set this member to CP_WINANSI. An application that uses the 
OEM character set should set this member to the value returned by the GetKB- 
CodePage function. For more information about the OEM character set, see the 
Microsoft Windows Guide to Programming. 


dwLangID | | | 
Specifies the language identifier for topic-name and item-name strings. 


dwSecurity 
Specifies a private (application-defined) security code. 


GetKBCodePage 
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CONVINFO 


Members 


d#Hinclude <ddeml.h> 


typedef struct tagCONVINFO { /* ci */ 
DWORD cb; 
~ DWORD hUser; 
HCONV hConvPartner; 


HSZ hszSvcPartner; 
HSZ hszServiceReq; 
HSZ hszTopic; 

HSZ hszItem; 

UINT wFmt ; 


UINT wlype; 

UINT wStatus; 

UINT wConvst; 

UINT wLastError; 

HCONVLIST hConvList; 

CONVCONTEXT ConvCtxt; 
} CONVINFO; 


The CONVINFO structure contains information about a dynamic data exchange ~ | 
(DDE) conversation. 


cb | 
Specifies the length of the structure, in bytes. 


hUser 
Identifies application-defined data. 


hConvPartner 
Identifies the partner application i in the DDE conversation. If the partner has not 
registered itself (by using the DdelInitialize function) to make DDE Manage- 
ment Library (DDEML) function calls, this member is set to 0. An application 
should not pass this member to any DDEML function except DdeQuery- 
Convinfo. | 


hszSvcPartner 
Identifies the service name of the partner application. 


hszServiceReq 
? Identifies the service name of the server application that was requested for con- 
nection. 


~ hszTopic 


Identifies the name of the requested spice. 


| hszItem 


Identifies the name of the requested item. This member is transaction- Baus 
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wFmt 


Specifies the format of the data being exchanged. This member is transaction- 


specific. 


wlype 


Specifies the type of the current transaction. This member is transaction- 
specific and can be one of the following values: 


Value 


XTYP_ADVDATA 


XTYP_ADVREQ 


XTYP_ADVSTART 


XTYP_ADVSTOP 
XTYP_CONNECT 


XTYP_CONNECT_CONFIRM 


XTYP_DISCONNECT 


XTYP_ERROR 


XTYP_EXECUTE 


XTYP_MONITOR 


XTYP_POKE 
XTYP_REGISTER 


XTYP_REQUEST 
XTYP_UNREGISTER 


XTYP_WILDCONNECT 


XTYP_XACT COMPLETE 


Meaning 


Informs a client that advise data from a server 
has arrived. 

Requests that a server send updated data to the 
client during an advise loop. This transaction re- 
sults when the server calls the DdePostAdvise 
function. 

Requests that a server begin an advise loop 
with a client. 

Notifies a server that an advise loop is ending. 
Requests that a server establish a conversation 
with a client. 

Notifies a server that a conversation with a 
client has been established. 

Notifies a server that a conversation has termi- 
nated. 

Notifies a DDEML application that a critical 
error has occurred. The DDEML may have in- 
sufficient resources to continue. 

Requests that a server execute a command sent 
by a client. | 

Notifies an application registered as 
APPCMD_MONITOR of DDE data being 
transmitted. 

Requests that a server accept unsolicited data 
from a client. 

Notifies other DDEML applications that a 
server has registered a service name. 


Requests that a server send data to a client. 


Notifies other DDEML applications that a 
server has unregistered a service name. 
Requests that a server establish multiple con- 
versations with the same client. 


Notifies a client that an asynchronous data 
transaction has completed. 
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wStatus | 
Specifies the status of the current conversation. This member can be a combina- 
tion of the following values: 


ST_ADVISE ST_INLIST 
ST_BLOCKED ST_ISLOCAL 
ST_BLOCKNEXT ST_ISSELF 
ST_CLIENT ST_TERMINATED 
ST_CONNECTED 
wConvst 
Specifies the conversation state. This member can be one of the following 
values: 
XST_ADVACKRCVD XST_INIT1 
XST_ADVDATAACKRCVD XST_INIT2 
XST_ADVDATASENT XST_NULL 
XST_ADVSENT XST_POKEACKRCVD 
XST_CONNECTED | XST_POKESENT . 
XST_DATARCVD ! XST_REQSENT 
XST_EXECACKRCVD _ XST_UNADVACKRCVD 
XST_EXECSENT XST_UNADVSENT | 
XST_INCOMPLETE 
wLastError | 
Specifies the error value associated with the last transaction. | 
hConvList | 


If the handle of the current conversation is in a conversation list, identifies the 
conversation list. Otherwise, this member is NULL. 


ConvCtxt 
Specifies the conversation context. 


See Also - CONVCONTEXT 
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CPLINFO 


Members 


dFinclude <cpl.h> 


typedef struct tagCPLINFO { /* cpli */ 
int idIcon; 
int idName; 


int idInfo; 
LONG 1IData; 
} CPLINFO; 


The CPLINFO structure contains resource information and a user-defined value 
for an extensible Control Panel application. 


idIcon 
Specifies an icon resource identifier for the application 1 icon. This icon is dis- 
played in the Control Panel window. 


idName 
Specifies a string resource identifier for the application name. The name is the 
short string displayed below the application icon in the Control Panel window. 
The name is also displayed on the Settings menu of Control Panel. 


idInfo 
Specifies a string resource identifier for the application description. The descrip- 
tion is the descriptive string displayed at the bottom of the Control Panel win- 
dow when the application icon is selected. / 


IData 
Specifies user-defined data for the application. 
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CREATESTRUCT a ay 


typedet Struct tagCREATESTRUCT { /* cs */ 
void FAR* IpCreateParams; 
HINSTANCE hInstance; 


HMENU hMenu; 

HWND hwndParent; 
int cy; 

int Cx: 

int y; 

int x 

LONG style; 


LPCSTR lpszName; 

LPCSTR IpszClass; 

-DWORD dwExStyle; 
} CREATESTRUCT; 


The CREATESTRUCT structure defines the initialization parameters passed to 
the window procedure of an application. 


Members IpCreateParams 
Points to data to be used for creating the window. 


hInstance 
Identifies the module-instance handle of the jnddile that owns the new window. 


hMenu 
Identifies the menu to be used by the new window. 


hwndParent : 
Identifies the window that owns the new daw. This member is NULL if the 
new window is a top-level window. 


cy | 
Specifies the height of the new window. 
cx , 
Specifies the width of the new window. 


Specifies the y-coordinate of the upper-left corner of the new window. Coordi- 
nates are relative to the parent window if the new window is a child window. 
| Otherwise, the coordinates are relative to ) the screen origin. 


Specifies the x-coordinate of F the upper-left corner of the new window. Coordi- 
~ nates are relative to the parent window if the new window is a child window. 
Otherwise, the coordinates are relative to the screen origin. 


Style 
Se eal the style for the new window. 
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See Also 


CTLINFO 


Members 


IpszName 
Points to a null-terminated string that specifies the name of the new window. 


IpszClass , | 
Points to a null-terminated string that specifies the class name of the new win- 
dow. 


dwExStyle 
Specifies extended style for the new window. © 


CreateWindow | 


#tinclude <custcntl].h> 


typedef struct tagCTLINFO { 


UINT wVersion; : /* control version */ 
UINT wCtlTypes; /* control types  / 
char szClass[CTLCLASS]; /* control class name */ 
char szTitle[CTLTITLE]; /* control title ~~ #*/ 
char szReserved[1@]; /* reserved for future use */ 
CTLTYPE Type[CTLTYPES]; /* control type list a / 


} CTLINFO; 


The CTLINFO structure defines the class name and version number for a custom 
control. The CTLINFO structure also contains an array of CTLTYPE structures, 
each of which lists commonly used combinations of control styles (called vari- 
ants), with a short description and information about the suggested size. 


wVersion , 
Specifies the control version number. Although you can start your numbering 
scheme from one digit, most implementations use the lower two digits to repre- 
sent minor releases. 


wCtlTypes 
Specifies the number of control types supported by this class. This value should 
always be greater than zero and less than or equal to the CTLTYPES value. 


szClass 
Specifies a null-terminated string that contains the control class name supported 
_ by the dynamic-link library (DLL). This string should be no longer than the 
CTLCLASS value. 


Comments 


See Also 
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szTitle : 
Specifies a null- terminated string that contains various copyright or author in- 


formation relating to the control library. This string should be no longer than 
the CTLTITLE value. 


Type 
Specifies an array of CTLTYPE structures containing information that relates 
to each of the control types supported by the class. There should be no more ele- 
ments in the array than specified by the CTLTYPES value. 


An application calls the ClassInfo function to retrieve basic information about the 
control library. Based on the information returned, the application can create in- 
stances of a control by using one of the supported styles. For example, Dialog 
Editor calls this function to query a library about the different control styles it can © 
display. 


The return value of the ClassInfo function identifies a CTLINFO structure if the 


function is successful. This information becomes the property of the caller, which 


must explicitly release it by using the GlobalFree function when the structure is 
no longer needed. — 


CTLSTYLE, CTLTYPE 


CTLSTYLE 


include <custcntl .h> 


typedef struct tagCTLSTYLE { 


UINT wX; /* x-origin of control * / 
UINT wy; /* y-origin of control */ 
UINT wCx;  /* width of control * / 
UINT wCy; : /* height of control — */ 
UINT wid; /* control child id * / 
DWORD = dwStyle; /* control style + / 
char szClass[CTLCLASS]; /* name of control class */ 
char  szTitle[CTLTITLE]; /* control text * / 


Fk GEESTYLE: 


The CTLSTYLE structure specifies the attributes of the selected control, includ- 
ing the current style flags, location, dimensions, and associated text. 
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Members wX 
Specifies the x-origin, in screen coordinates, of the control relative to the client 
area of the parent window. 
wY | 
Specifies the y-origin, in screen coordinates, of the control relative to the client 
area of the parent window. 


wCx 
Specifies the current control width, in screen coordinates. 


wCy 
Specifies the current control height, in screen coordinates. 


wld 
Specifies the current control identifier. In most cases, you should not allow the 
user to change this value because Dialog Editor automatically coordinates it 
with a header file. 


dwStyle 
Specifies the current control style. The high-order word contains the control- 
specific flags, and the low-order word contains the Windows-specific flags. 
You may let the user change these flags to any values supported by your control 
library. 

szClass 
Specifies a null-terminated string representing the name of the current control 
class. You should not allow the user to edit this member, because it is provided 
for informational purposes only. This string should be no longer than the 
CTLCLASS value. 


szTitle 
Specifies with a null-terminated string the text associated with the control. 
This text is usually displayed inside the control or may be used to store other 
associated information required by the control. This string should be no longer 
than the CTLTITLE value. : 


Comments An application calls the ClassStyle function to display a dialog box to edit the 
style of the selected control. When this function is called, it should display a 
modal dialog box in which the user can edit the CTLSTYLE members. The user 
interface of this dialog box should be consistent with that of the predefined con- 
trols that Dialog Editor supports. 


See Also CTLINFO, CTLTYPE 


CTLTYPE 


Members 


See Also 
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[3.1 | 


#Finclude <custcnt1.h> 


typedef struct tagCTLTYPE { 


UINT wlype; /* type style * / 

UINT wWidth; /* suggested width */ 

UINT wHeight; /* suggested height */ 

DWORD = dwStyle; /* default style * / 

char szDescrLCTLDESCR]; /* menu name * / 
} CTLTYPE; | 


The CTLTYPE structure contains information about a control in a particular 
class. The CTLINFO structure includes an array of CTLTYPE structures. 


wlype | 
Reserved; must be zero. 

wWidth | 
Specifies the suggested width of the control when created with Dialog Editor. 
The width is specified in resource-compiler coordinates. 


wHeight | | 
Specifies the suggested height of the control when created using Dialog Editor. 
The height is specified in resource-compiler coordinates. 


dwStyle 
Specifies the initial style bits used to obtain this control type. This value in- 
cludes the control-defined flags in the high-order word and the Windows- 
defined flags in the low-order word. 


szDescr 
Defines the name to be used by other development tools when referring to this 
particular variant of the base control class. Dialog Editor does not refer to this 
information. This string should not be longer than the CTLDESCR value. 


CTLINFO, CTLSTYLE 
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DCB [ 2.x | 


typedef struct tagDCB /* dcb | o*/ 

f | 
BYTE Id; /* internal device identifier * / 
UINT BaudRate; /* baud rate * / 
BYTE ByteSize; /* number of bits/byte, 4-8 * / 
BYTE Parity; /* @-4=none,odd,even,mark,space * / 
BYTE StopBits; /* @,1,2 = 1, 1.5, 2 * / 
UINT RlsTimeout; /* timeout for RLSD to be set * / 
UINT CtsTimeout; /* timeout for CTS to be set * / 
UINT DsrTimeout; /* timeout for DSR to be set * / 


UINT fBinary 


:1; /* binary mode (skip EOF check) * / 
UINT fRtsDisable 21; /* don't assert RTS at init time */ 
UINT fParity 21; /* enable parity checking * / 
UINT fOutxCtsFlow :1; /#* CTS handshaking on output + / 
UINT fOutxDsrFlow :1; /* DSR handshaking on output * / 
UINT fDummy :2; /* reserved * / 
UINT fDtrDisable :1;  /* don't assert DTR at init time * / 
UINT fOutx :1;  /* enable output XON/XOFF x / 
UINT fInx 21; /* enable input XON/XOFF * / 
UINT fPeChar :1; /* enable parity err replacement = */ 
UINT fNull :1; /* enable null stripping * / 
UINT fChEvt 21;  /* enable Rx character event * / 
UINT fDtrflow :1;  /* DTR handshake on input * / 
UINT fRtsflow :1; /* RTS handshake on input a / 
UINT fDummy2 ae 
char XonChar; /* Tx and Rx XON character a / 
char XoffChar; /* Tx and Rx XOFF character * / 
UINT XonLim; /* transmit XON threshold * / 
UINT XoffLim; /* transmit XOFF threshold * / 
char PeChar; /* parity error replacement char * / 
char EofChar; /* end of Input character * / 
char EvtChar; /* received event character * / 
UINT TxDelay; /* amount of time between chars * / 

} DCB; 


The DCB structure defines the control setting for a serial communications device. 


Members | Id | | | 
Specifies the communication device. This value is set by the device driver. If 
the most significant bit is set, the DCB structure is for a parallel device. 


BaudRate — 
Specifies the baud rate at which the communications device operates. If the 
value of the high-order byte is equal to OxFF, the low-order byte specities a 
baud-rate index. The index can be one of the following values: 


CBR_110 
CBR_4400 
CBR_9200 
CBR_8400 
CBR_6000 
CBR_28000 
CBR_9600 
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CBR_14400 
CBR_19200 
CBR_38400 
CBR_56000 
CBR_128000 
CBR_256000 


If the high-order byte is not equal to OxFF, this parameter specifies the actual 


baud rate. 
ByteSize 


Specifies the number of bits in the characters transmitted and received. This 


member can be 


Parity 


any number from 4 through 8. 


Specifies the parity scheme to be used. This member can be any one of the fol- 


lowing values: 


Value Meaning 
EVENPARITY Even 
MARKPARITY Mark 
NOPARITY No parity 
ODDPARITY Odd 
StopBits | 
Specifies the number of stop bits to be used. This member can be any one of the 
following values: 
Value — Meaning 
ONESTOPBIT 1 stop bit 
ONESSTOPBITS 1.5 stop bits 
TWOSTOPBITS 2 stop bits 
RisTimeout 


Specifies the maximum amount of time, in milliseconds, the device should wait 
for the RLSD (receive-line-signal-detect) signal. RLSD is also known as the 
- carrier-detect (CD) signal. 


CtsTimeout 


Specifies the maximum amount of time, in milliseconds, the Aye should wait 
for the CTS (clear-to-send) signal. 


DsrTimeout 


Specifies the maximum amount of time, in milliseconds, the device should wait | 
for the DSR (data-set-ready) signal. 
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fBinary 
Specifies binary mode. In nonbinary mode, the EofChar character is recog- 
nized on input and remembered as the end of data. 


fRtsDisable 
Specifies whether or not the RTS (request-to-send) signal is disabled. If this 
member is set, RTS is not used and remains low. If this member is clear, RTS is 
sent when the device is opened and turned off when the device is closed. 


fParity | 
Specifies whether parity checking is enabled. If this member is set, parity check- 
ing is performed and errors are reported. 


fOutxCtsFlow 
Specifies that CTS (clear-to-send) signal is to be monitored for output flow con- 
trol. If this member is set and CTS is turned off, output is suspended until CTS 
is again sent. 


fOutxDsrFlow 
Specifies that the DSR (data-set-ready) signal is to be monitored for output 
flow control. If this member is set and DSR is turned off, output is suspended 
until DSR is again sent. 


fDummy 
Reserved. 


fDtrDisable 
Specifies whether the DTR (data-terminal- -ready) signal is disabled. If this mem- 
ber is set, DTR is not used and remains low. If this member is clear, DTR is 
sent when the device is opened and turned off when the device is closed. 


fOutX 
Specifies that XON/XOFF flow control is used during transmission. If this 
member is set, transmission stops when the XoffChar character is received and 
starts again when the XonChar character is received. 


fInX 
Specifies that XON/XOFF flow control is used ane reception. If this mem- 
ber is set, the XonChar character is sent when the reception queue comes 
within XoffLim characters of being full and the XonChar character is sent 
when the reception queue comes within XonLim characters of being empty. 


fPeChar | 
Specifies that characters reecived with parity errors are to be replaced with the 
character specified by this member. This member must ee set for the Sas 
ment to occur. 


fNull | 
Specifies that received null characters are to be discarded. 


See Also 
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fChEvt 
Specifies that reception of the EvtChar character is to be flagged as an event. 


{Dtrflow 
Specifies that the DTR (data-terminal-ready) signal is to be used for reception 
flow control. If this member is set, DTR is turned off when the reception queue 
comes within XoffLim characters of being full and sent when the reception 
queue comes within XonLim characters of being empty. 


{Rtsflow 
Specifies that the RTS (ready-to-send) signal is to be used for reception flow 
control. If this member is set, RTS is turned off when the reception queue 
comes within XoffLim characters of being full, and sent when the reception 
queue comes within XonLim characters of being empty. 

fDummy2 
Reserved. 

XonChar 
Specifies the value of the XON character for both transmission and reception. 


XoffChar 
Specifies the value of the XOFF character for both transmission and reception. 


XonLim 
Specifies the minimum number of characters allowed in the reception queue 
before the XON character is sent. 


XoffLim 
Specifies the maximum number of characters allowed in the reception queue 
before the XOFF character is sent. The value of the XoffLim member is sub- 
tracted from the size of the reception queue, in bytes, to calculate the maximum 
number of characters allowed. 


PeChar 
Specifies the value of the character used to replace sneer received with a 
parity error. 


EofChar 
Specifies the value of the character used to signal the end of data. 


EvtChar 
Specifies the value of the enue used to nee an event. 


TxDelay 
Not currently used. 


BuildCommDCB, GetCommState, SetCommState 
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DDEACK 


Members 


See Also 


dFinclude <dde.h> 


typedef struct tagDDEACK { /* ddeack */ 
WORD bAppReturnCode:8, | . 
reserved:6, 
fBusy:1, 
fAck:1; 
} DDEACK; 


The DDEACK structure contains status flags that a DDE application passes to its 
partner as part of the WM_DDE_ACK message. The flags provide details about 
the application’s response to a WM_DDE_ADVISE, WM_DDE_DATA, 
WM_DDE_EXECUTE, WM_DDE_REQUEST, WM_DDE_POKE, or 
WM_DDE_UNADVISE message. 


bAppReturnCode 
Specifies an application-defined return code. 


fBusy 
Indicates whether the application was busy and unable to respond to the part- 
ner’s message at the time the message was received. A nonzero value indicates 
the server was busy and unable to respond. The {Busy member is defined only 
when the fAck member is zero. 


fAck 
Indicates whether the application accepted the message from its partner. A non- 
zero value indicates the server accepted the message. 


WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_DATA, 


-WM_DDE_EXECUTE, WM_DDE_REQUEST, WM —DDE_ POKE, 


WM_DDE_UNADVISE, 


DDEADVISE 


Members | 


See Also 
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[ 2.x ] 


#Hinclude <dde.h> 


typedef struct tagDDEADVISE { /* ddeadv */ 
WORD reserved:14, 
fDeferUpd:1, 
fAckReq:1; 
short cfFormat; 
} DDEADVISE; 


The DDEADVISE structure contains flags that specify how a server should 
send data to a client during an advise loop. A client passes the handle of a 
DDEADVISE structure to a server as part of aWM_DDE_ADVISE message. 


fDeferUpd 
Indicates whether the server should defer sending updated data to the client. A 
- nonzero value tells the server to send a WM_DDE_DATA message with a 
NULL data handle whenever the data item changes. In response, the client can 
post a WM_DDE_REQUEST message to the server to obtain a handle to the 
updated data. . 


| fAckReq 


Indicates whether the server should set the fAckReq flag in the 
WM_DDE_DATA messages that it posts to the client. A nonzero value tells the 
server to set the fAckRegq bit. 


cfFormat 
Specifies the client application’s preferred data format. The format must be a 
standard or registered clipboard format. The euowane standard clipboard for- 
mats may be used: 


CF_BITMAP CF_OEMTEXT 
CF_DCF_OEMTEXT CF_PALETTE 
CF_DCF_PALETTE CF_PENDATA 
CF_DCF_PENDATA CF_SYLK 
CF_DCF_SYLK CF_TEXT 
CF_DCF_TEXT CF_TIFF 
CF_METAFILEPICT 


WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_UNADVISE 
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DDEDATA 


- Members 


See Also 


#FHinclude <dde.h> 


typedef struct tagDDEDATA { /* ddedat */ 
WORD unused:12, 
fResponse:1l, 
fRelease:l, 
reserved:1l, 
fAckReq:1; 
short cfFormat; 
BYTE Value[1]; 
} DDEDATA; 


| The DDEDATA structure contains the data andl information about the data sent as 


part of aWM_DDE_DATA message. 


fResponse 
Indicates whether the application receiving the WM_DDE_DATA message 
should acknowledge receipt of the data by sending a WM_DDE_ACK mes- 
sage. A nonzero value indicates the application should send the acknow- 
ledgment. 


fRelease 
Indicates if the application receiving the WM_DDE_POKE message should 
free the data. A nonzero value indicates the data should be freed. 


fAckReq — 
Indicates whether the data was sent in response toa WM_DDE_REQUEST 
message ora WM_DDE_ADVISE message. A nonzero value indicates the data 
was sent in response toa WM_DDE_REQUEST message. 


cfFormat 
Specifies the format of the data. The format should be a standard or registered 
clipboard format. The following standard clipboard formats may be used: 


CF_BITMAP CF_OEMTEXT 
CF_DCF_OEMTEXT CF_PALETTE _ 
CF_DCF_PALETTE CF_PENDATA 
CF_DCF_PENDATA CF_SYLK 
CF_DCF_SYLK CF_TEXT 
CF_DCF_TEXT CF_TIFF | 
CF_METAFILEPICT 


-WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_POKE, 
WM_DDE_REQUEST 


DDEPOKE 273 


DDEPOKE | — [ax] 


#Hinclude <dde.h> 


typedef struct tagDDEPOKE { /* ddepok */ 
WORD unused:13, 
fRelease:1, 
fReserved:2; 
short cfFormat; 
BYTE Value[1]; 
} DDEPOKE; . 


The DDEPOKE structure contains the data and information about the data sent as 
part of a WM_DDE_POKE message. 


Members fRelease 
Indicates if the application receiving the WM_DDE_POKE message should 
free the data. A nonzero value specifies the data should be freed. 


cfFormat 
Specifies the format of the data. The format should be a standard or registered 
clipboard format. The following standard clipboard formats may be used: 


CF_BITMAP CF_OEMTEXT 
CF_DCF_OEMTEXT CF_PALETTE 

~ CF_DCF_PALETTE CF_PENDATA 
CF_DCF_PENDATA CF_SYLK 


CF_DCF_SYLK CF_TEXT 
CF_DCF_TEXT CF_TIFF 
CF_METAFILEPICT 
Value 
Contains the data. The size of this array depends on the value of the cfFormat 
member. 7 


See Also WM_DDE _POKE 
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DEBUGHOOKINFO aad 


Members 


See Also 


typedef struct tagDEBUGHOOKINFO { 
HMODULE hModuleHook; 
LPARAM reserved; 
LPARAM 1Param; 
WPARAM wParam;. 
int code; 
} DEBUGHOOKINFO; 


| The DEBUGHOOKINEFO structure contains debugging information. 


hModuleHook 
Identifies the module containing the filter function. 


reserved 
Not used. 


[Param 
Specifies the value to be passed to the hook in the /Param parameter of the 
DebugProc callback function. 


wParam 


Specifies the value to be saaied to the hook in the wParam parameter of the 
DebugProc callback function. 


code | 
Specifies the value to be passed to the hook in the code parameter of the Debug- 
Proc callback function. 


DebugProc, SetWindowsHook 


_DELETEITEMSTRUCT 


typedef struct tagDELETEITEMSTRUCT { /* deli */ 
UINT CtlType; | 
UINT CtlID; 
UINT itemID; 
HWND hwndItem; 
DWORD itemData; 

} DELETEITEMSTRUCT; 


The DELETEITEMSTRUCT structure describes a deleted owner-drawn 


list-box or combo-box item. When an item is removed from the list box or 
combo box or when the list box or combo box is destroyed, Windows sends the 


Members 


See Also — 


DEVMODE 


DEVMODE 


WM_DELETEITEM message to the owner for each deleted item. The /Param 
parameter of the message contains a pointer to this structure. 


CtlType 
Contains ODT_LISTBOX (which specifies an owner-drawn list box) or 
ODT_COMBOBOxX (which specifies an owner-drawn combo box). 
cup | | 
- Contains the control identifier for the list box or combo box. 
itemID | - : 
Contains the index of the item in the list box or combo box being removed. 


hwndItem 
Contains the window handle of the control. 


itemData 


Contains the value passed to the control in the /Param parameter of the 
LB_INSERTSTRING, LB_ADDSTRING, CB_INSERTSTRING, or 
CB_ADDSTRING message when the item was added to the list box. 


WM_DELETEITEM 


#Hinclude <print.h> 


typedef struct tagDEVMODE { /* dm */ 


char dmDeviceName[CCHDEVICENAME]; 
UINT dmSpecVersion; 
UINT dmDriverVersion; 
UINT dmSize; 
UINT dmDrivereExtra; 
DWORD dmFields; 
int dmOrientation; 
int  dmPaperSize; 
int  dmPaperLength; 
int dmPaperWidth; 
int. dmScale; 
int  dmCopies; 
int dmDefaultSource; 
int dmPrintQuality; 
int dmColor; | 
int dmDuplex; — 
int  dmYResolution; 
| int dmTTOption; 
} DEVMODE; 
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Members 


The DEVMODE structure contains information about a printer driver’s initializa- 
tion and environment data. An application passes this structure to the Device- 
Capabilities and ExtDeviceMode functions. 


dmDeviceName 
Specifies the name of the device the driver supports—for example, “PCL/HP 
LaserJet” in the case of the Hewlett-Packard LaserJet. Each driver has a unique 
string. 


dmSpec Version 
Specifies the version number of the DEVMODE structure. For Windows ver- 
sion 3.1, this value should be 0x30A. | 


dmDriver Version 
Specifies the printer driver version number assigned by the printer driver 
developer. 


dmSize 
Specifies the size, in bytes, of the DEVMODE structure. (This value does not 
include the optional dmDriverData member for device-specific data, which 
can follow the structure.) If an application manipulates only the driver-inde- 
pendent portion of the data, it can use this member to find out the length of the 
structure without having to account for different versions. 


dmDriverExtra | 
Specifies the size, in bytes, of the optional dmDriverData member for device- 
specific data, which can follow the structure. If an application does not use 
device-specific information, it should set this member to zero. 


dmFields 


Specifies a set of flags that indicate which of the remaining members in the 
DEVMODE structure have been initialized. It can be any combination (or it 
can be none) of the following values: 


Constant Value 
DM_ORIENTATION 0x0000001L 
DM_PAPERSIZE 0x0000002L 
DM_PAPERLENGTH 0x0000004L 
DM_PAPERWIDTH 0x0000008L 
DM_SCALE 0x0000010L 
DM_COPIES 0x0000100L 
DM_DEFAULTSOURCE — 0x0000200L 
DM_PRINTQUALITY 0x0000400L 
DM_COLOR 0x0000800L 
DM_DUPLEX 0x0001000L 
DM_YRESOLUTION 0x0002000L. 
DM_TTOPTION 0x0004000L 
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A printer driver supports only those members that are appropriate for the 


printer technology. 


dmOrientation 


Specifies the orientation of the paper. It can be either 
DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE. 


dmPaperSize 


Specifies the size of the paper to print on. This member may be set to zero 

if the length and width of the paper are specified by the dmPaperLength and 
dmPaperWidth members, respectively. Otherwise, the dmPaperSize member 
can be set to one of the following predefined values: 


Value 


DMPAPER_ FIRST 
- DMPAPER_LETTER 
DMPAPER_LETTERSMALL 
DMPAPER_TABLOID 
DMPAPER_LEDGER 
DMPAPER_LEGAL 
DMPAPER_STATEMENT 
-DMPAPER_EXECUTIVE 
DMPAPER_A3 | 
DMPAPER_A4 
DMPAPER_A4SMALL 
DMPAPER_A5 
DMPAPER_B4 
DMPAPER_B5. 
‘DMPAPER_ FOLIO | 
DMPAPER_QUARTO_ 
DMPAPER_10X14 
DMPAPER_11X17 _ 
DMPAPER_NOTE 
DMPAPER_ENV_9 
DMPAPER_ENV_10 
-DMPAPER_ENV_11 
DMPAPER_ENV_12 
DMPAPER_ENV_14 
DMPAPER_CSHEET 
DMPAPER_DSHEET 
_ DMPAPER_ESHEET 
DMPAPER_ENV_DL 


Meaning 


DMPAPER_LETTER 
Letter, 8 1/2 x 11 in. 

Letter Small, 8 1/2 x 11 in. 
Tabloid, 11 x 17 in. 

Ledger, 17 x 11 in. 

Legal, 8 1/2 x 14 in. 
Statement, 5 1/2 x 8 1/2 in. 
Executive, 7 1/2 x 10 1/2 in. 
A3, 297 x 420 mm 

A4, 210 x 297 mm 

A4 Small, 210 x 297 mm 


AS, 148 x 210 mm 


B4, 250 x 354 mm 
B5, 182 x 257 mm 


Folio, 8 1/2 x 13 in. 


Quarto, 215 x 275 mm 

10 x 14 in. 

11 x 17 in. 

Note, 8 1/2 x 11 in. 

Envelope #9, 3 7/8 x 8 7/8 in. 
Envelope #10, 4 1/8 x9 1/2 in. 
Envelope #11, 4 1/2 x 10 3/8 in. 
Envelope #12, 4 1/2 x 11 in. 
Envelope #14, 5 x 11 1/2 in. 

C size sheet 

D size sheet 


_E size sheet 


Envelope DL, 110 x 220 mm 
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Value 


- DMPAPER_ENV_C3 


DMPAPER_ENV_C4 
DMPAPER_ENV_C5 
DMPAPER_ENV_C6 
DMPAPER_ENV_C65 
DMPAPER_ENV_B4 
DMPAPER_ENV_B5 
DMPAPER_ENV_B6 
DMPAPER_ENV_ITALY 


~ DMPAPER_ENV_MONARCH 


DMPAPER_ENV_PERSONAL 
DMPAPER_FANFOLD_US 


DMPAPER_FANFOLD_STD_GERMAN 


DMPAPER_FANFOLD_LGL_GERMAN 
DMPAPER_LAST 
DMPAPER_USER 


Meaning | 


Envelope C3, 324 x 458 mm 
Envelope C4, 229 x 324 mm 
Envelope C5, 162 x 229 mm 
Envelope C6, 114 x 162 mm 
Envelope C65, 114 x 229 mm 


_ Envelope B4, 250 x 353 mm 


Envelope B5, 176 x 250 mm 
Envelope B6, 176 x 125 mm 
Envelope, 110 x 230 mm 

Envelope Monarch, 3 7/8 x 7 1/2 in. 
Envelope, 3 5/8 x 6 1/2 in. 


U.S. Standard Fanfold, 
14 7/8 x 11 in. 


German Standard Fanfold, 
8 1/2 = 12in. 


German Legal Fanfold, 8 1/2 x 13 in. 
German Legal Fanfold, 8 1/2 x 13 in. 
User-defined 


dmPaperLength 
Specifies a paper length, in tenths of a millimeter. This parameter overrides the 
paper length specified by the dmPaperSize member, either for custom paper 
sizes or for such devices as dot-matrix printers that can print on a variety of 
page sizes. 


dmPaper Width 
Specifies a paper width, in tenths of a millimeter. This parameter overrides the 
paper width specified by the dmPaperSize member. 


~dmScale 


Specifies the factor by which the printed output is to be scaled. The apparent 
page size is scaled from the physical page size by a factor of dmScale/100. For 
example, a letter-size paper with a dmScale value of 50 would contain as much 
data as a page of size 17 by 22 inches because the output text and graphics 
would be half their cee height and width. 


dm Copies 
Specifies the number of copies pe if the device SuppeHs multiple-page co- 
pies. 


dmDefaultSource 
Specifies the default bin from which the paper is fed. The application can over- 
ride this value by using the GETSETPAPERBINS escape. This member can be 
one of the following values: 
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DMBIN_AUTO DMBIN_LOWER 


DMBIN_CASSETTE DMBIN_MANUAL 
DMBIN_ENVELOPE DMBIN_MIDDLE 
DMBIN_ENVMANUAL DMBIN_ONLYONE | 
DMBIN_FIRST DMBIN_SMALLFMT 
DMBIN_LARGECAPACITY DMBIN_TRACTOR 
DMBIN_LARGEFMT DMBIN_UPPER 
DMBIN_LAST 


A range of values is reserved for device-specific bins. To be consistent with in- 
itialization information, the GETSETPAPERBINS and ENUMPAPERBINS 
escapes use these values. 


-dmPrintQuality | 
_ Specifies the printer resolution. Following are the four predefined device- 
independent values: 


DMRES_ HIGH (-4) 

DMRES_ MEDIUM (-3) 
_ DMRES_LOW (-2) 

DMRES_DRAFT (-1) 


If a positive value is given, it specifies the number of dots per inch (DPI) and is 
therefore device-dependent. | = 


If the printer initializes the dmYResolution member, the dmPrintQuality 
member specifies the x-resolution of poe printer, in dots per inch. 


dmColor 
Specifies whether. a color Srintel is to sider color or monochrome output. 
Possible values are: | | | 


DMCOLOR_COLOR (1) 
DMCOLOR_MONOCHROME (2) 


dmDuplex 
Specifies duplex (double-sided) printing for printers capable of duplex printing, 
This member can be one of the following values: 


DMDUP_SIMPLEX (1) 
DMDUP_HORIZONTAL (2) 
DMDUP_VERTICAL (3) 


dmY Resolution | 
Specifies the y-resolution of the printer, in dots per inch. If the printer initializes 
this member, the dmPrintQuality member specifies the x- resolution oe me 
printer, in dots per inch. 


_ dmTTOption 
Specifies how TrueType fonts should be printed. It can be one of the following: 
- values: | 
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Comments 


See Also | 


DEVNAMES 


Value Meaning 


DMTT_BITMAP Print TrueType fonts as graphics. This is the default 
action for dot-matrix printers. 

DMTT_DOWNLOAD Download TrueType fonts as soft fonts. This is the 
default action for Hewlett-Packard printers that use 
Printer Control Language (PCL). 

DMTT_SUBDEV Substitute device fonts for TrueType fonts. This is the 
default action for PostScript printers. 


Only drivers that are fully updated for Windows versions 3.0 and later and that 
export the ExtDeviceMode function use the DEVMODE structure. 


An application can retrieve the paper sizes and names supported by a printer by 
calling the DeviceCapabilities function with the DC_PAPERS, DC_PAPERSIZE, 
and DC_PAPERNAMES values. 


Before setting the value of the dmTTOption member, applications should find 
out how a printer driver can use TrueType fonts by calling the DeviceCapabilities 
function with the DC_TRUETYPE value. 


Drivers can add device-specific data ees following the DEVMODE 
structure. 


DeviceCapabilities, ExtDeviceMode © 


#Finclude <commdlg.h> 


typedef struct tagDEVNAMES { /* dn */ 
UINT wDriverOffset; 
UINT wDeviceOffset; 
UINT wOutputOffset; 
UINT wDefault; 
/* optional data may appear here */ 
} DEVNAMES; 


The DEVNAMES structure contains offsets to strings that specify the driver, 
name, and output port of a printer. The PrintDlg function uses these strings to ini- 
tialize controls in the system-defined Print dialog box. When the user chooses the 
OK button to close the dialog box, information about the selected printer is re- 
turned in this structure. | 


Members 


See Also — 


DOCINFO 
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wDriverOffset 
Specifies the offset from the beginning of the structure to a null-terminated 
string that specifies the Microsoft MS-DOS® filename (without extension) of 
the device driver. On input, this string is used to set which printer to initially 
display in the dialog box. ! 


wDeviceOffset 
Specifies the offset from the beginning of the structure to the null-terminated 
string that specifies the name of the device. This string cannot exceed 32 
bytes in length, including the null character, and must be identical to the 
dmDeviceName member of the DEVMODE structure. 


wOutputOffset 
Specifies the offset from the beginning of the structure to the null-terminated 
string that specifies the MS-DOS device name for the physical output medium 
(output port). 


wDefault 
Specifies whether the strings specified in the DEVNAMES structure identify 
the default printer. It is used to verify that the default printer has not changed 
since the last print operation. On input, this member can be set to 
DN_DEFAULTPRN. If the DN_DEFAULTPRN flag is set, the other values in 
the DEVNAMES structure are checked against the current default printer. 


On output, the wDefault member is changed only if the Print Setup dialog box 
was displayed and the user chose the OK button to close it. If the default printer 
was selected, the DN_DEFAULTPRN flag is set. If a printer is specifically 

_ selected, the flag is not set. All other bits in this member are reserved for inter- 
nal use by the dialog box procedure of the Print dialog box. 


PrintDig — 


typedef struct { /* di */ 
int cbSize; 
LPCSTR JIpszDocName; 
LPCSTR IpszOutput; 

} DOCINFOs 


The DOCINFO structure contains the input pi output filenames used oe the 


~ StartDoc function. 
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Members cbSize 
| Specifies the size of the structure, in bytes. 


IpszDocName 
Points to a null-terminated string specifying the name of the document. This 
string must not be longer than 32 characters, including the null terminating char- 
acter. : 


IpszOutput - 
Points to a null-terminated string specifying the name of an output file. This al- 
lows a print job to be redirected to a file. If this value is NULL, output goes to 
the device for the specified device context. . 


See Also | StartDoc 
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typedef struct tagDRAWITEMSTRUCT { /* ditm */ 
UINT CtlType; 
UINT CtlID; 
UINT itemID; 
UINT itemAction; 
UINT itemState; 
HWND hwndItem; 
HDC hDC; 
RECT rcItem; 
DWORD itemData; 

} DRAWITEMSTRUCT; 


The DRAWITEMSTRUCT structure provides information the owner needs to 
determine how to paint an owner-drawn control. The owner of the owner-drawn 
control receives a pointer to this structure as the /Param parameter of the 
WM_DRAWITEM message. © 


Members -CtlType | 
Specifies the control type. The values for control types follow: 
Value . Meaning 
ODT_BUTTON ~ Owner-drawn button 
_ ODT_COMBOBOX — Owner-drawn combo box 
ODT_LISTBOX Owner-drawn list box. 


ODT_MENU | | Owner-drawn menu 
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CtlID 
Specifies the control identifier for a combo box, list box or button. This mem- 
ber is not used for a menu. 


itemID 

Specifies the menu-item identifier for a menu or the index of the item in a list 
box or combo box. For an empty list box or combo box, this member is a nega- 
tive value. This allows the application to draw only the focus rectangle at the 
coordinates specified by the rcItem member even though there are no items in 
the control. This indicates to the user whether the list box or combo box has 

_ input focus. The itemAction member determines whether the rectangle is to be 
drawn as though the list box or ‘combo box has input focus. 7 


itemAction 
Specifies the drawing action required. as member is one or more of the fol- 
lowing values: 


Value — Meaning | 
ODA_DRAWEN TIRE Bit is set when the entire control needs to be drawn. 
ODA_FOCUS Bit is set when the control gains or loses input focus. 


The itemState member should be checked to determine 
whether the control has focus. 


ODA_SELECT Bit is set when only the selection status has changed. 
The itemState member should be checked to determine 
the new selection state. 


itemState _ , 
Specifies the visual state of the item after the current drawing action takes 
place; that is, if a menu item is to be grayed, the state flag ODS_GRAYED will 
be set. Following are the state flags: 


Value | Meaning 


ODS_CHECKED Bit is set if the menu item is to be checked. This bit is used 
only ina menu. 


ODS_DISABLED Bit is set if the item is to be drawn as disabled. 


ODS_FOCUS Bit is set if the item has input focus. 
ODS_GRAYED Bit is set if the item is to be grayed. This bit is used only ina 
menu. 


~ ODS_SELECTED Bit is set if the item’s status is selected. 


hwndIitem 
Specifies the window handle of the control for combo boxes, list boxes, and but- 
tons. For menus, it contains the handle of the menu CE) containing the 
item. 3 7 


hDC 


Identifies a device context; this device context must be used when performing 
drawing operations on the control. 
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-DRIVERINFOSTRUCT 


Members 


See Also 


rcitem | 
Specifies a rectangle in the device context identified by the hDC member that 
defines the boundaries of the control to be drawn. Windows automatically clips 
anything the owner draws in the device context for combo boxes, list boxes, 
and buttons, but it does not clip menu items. When drawing menu items, it must 
ensure that the owner does not draw outside the boundaries of the rectangle de- 
fined by the rcItem member. 


itemData | | | 
Contains the value last assigned to the list box or combo box by an LB_SET- 
ITEMDATA or CB_SETITEMDATA message. If the list box or combo box 
has the LBS_HASSTRINGS or CBS_HASSTRINGS style, this value is ini- 
tially zero. Otherwise, this value is initially the value that was passed to the list 
box or combo box in the /Param parameter of one of the following messages: 


CB_ADDSTRING 
CB_INSERTSTRING 
LB_ADDSTRING 
LB_INSERTSTRING 


typedef struct tagDRIVERINFOSTRUCT { /* drvinfst */ 
UINT length; | 
HDRVR hDriver; 
HINSTANCE hModule; 
char ~~ SzAliasName[128]; 

} DRIVERINFOSTRUCT; 


The DRIVERINFOSTRUCT structure eontaing basic information about an 
installable device driver. 


length | 7 
Specifies the size of the DRIVERINFOSTRUCT structure. 


_ hDriver 


Identifies an instance of the installable driver. 


hModule on 
Identifies an installable driver module. 


szAliasName _ am 
Points to a null-terminated string that specifies the driver name or an alias 
under which the driver was loaded. 


GetDriverInfo 
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DRVCONFIGINFO _ aa] 


typedef struct tagDRVCONFIGINFO a 
DWORD dwDCISize; 
LPCSTR) JIpszDCISectionName; 
LPCSTR JIpszDCIAliasName; 

} DRVCONFIGINFO; 


The DRVCONFIGINFO structure contains information about the entries for an 
installable device driver in the SYSTEM.INI file. This structure is sent in the 
lParam parameter of the DRV_CONFIGURE and DRV_INSTALL installable- 
driver messages. ty 


Members dwDCISize 
Specifies the size of the DRVCONFIGINFO structure. 


IpszDCISectionName 
Points to a null-terminated string that specifies the name of the section in the 
SYSTEM.INI file where driver information i iS recorded. 


IpszDCIAliasName 
Points to a null-terminated string that specifies the driver name or an alias 
under which the driver was loaded. 


— See Also — | DRV_CONFIGURE, DRV_INSTALL 


EVENTMSG ap hee [ 2.x | 
typedef struct tagEVENTMSG {  /* em */ | 
UINT message; 
UINT paramL; 
UINT param; 


DWORD time; 
} EVENTMSG; 


The EVENTMSG structure contains information from the Windows application 
queue. This structure is used to store message information for the Journal- 
PlaybackProc callback function. 


Members message 
Specifies the message number. 


paramL 
Specifies additional information about the message. The exact meaning de- 
pends on the message value. 
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See Also 


paramH 


Specifies additional information about the message. The exact meaning de- 
pends on the message value. 


time 


Specifies the time at which the message was posted. 


JournalPlaybackProc, SetWindowsHook 
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#include <commdlg.h> 


Members 


DWORD 
HWND 
HINSTANCE 
DWORD 
LPSTR 
LPSTR 
UINT 
UINT 
LPARAM 
UINT 
LPCSTR 


} FINDREPLACE; 


typedef struct tagFINDREPLACE { /* fr */ 


1StructSize; 
hwndOwner; 
hInstance; 

Flags; 
TpstrFindWhat; 
TpstrReplaceWith; 
wFindWhatLen; 
wReplaceWithLen; 
1CustData; 
(CALLBACK* 1pfnHook)(HWND, UINT, WPARAM, LPARAM) : 
lTpTemplateName; 


The FINDREPLACKE structure contains information that the system uses to in1- 
tialize a system-defined Find dialog box or Replace dialog box. After the user 
chooses the OK button to close the dialog box, the system returns information 

_ about the user’s selections in this structure. 


IStructSize 


Specifies the length of the structure, in bytes. This member is filled on input. 


hwndOwner 


Identifies the window that owns the dialogs box. This member can be any valid 
window handle, but it must not be NULL. 


_ If the FR_SHOWHELP flag is set, hwndOwner must identify the window that 
owns the dialog box. The window procedure for this owner window receives a 
notification message when the user chooses the Help button. (The identifier for 


the notification message is the value returned by the Register WindowMessage — 
function when HELPMSGSTRING is passed as its pire ) 


This member is filled on input. 
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hInstance 
Identifies a data block that contains a dialog box template specified by the © 
IpTemplateName member. This member is only used if the Flags member 
specifies the FR_-ENABLETEMPLATE or the 
FR_ENABLETEMPLATEHANDLE flag; otherwise, this member is ignored. 
This member is filled on input. | 


Flags | 
Specifies the dialog box initialization flags. This member can be a combination 
of the following values: 


Value | Meaning 


FR_DIALOGTERM Indicates the dialog box is closing. The 
window handle returned by the FindText 
or ReplaceText function is no longer 

_valid after this bit is set. This flag is set by 
the system. | | 


FR_DOWN Sets the direction of searches through a 
: document. If the flag is set, the search 

direction is down; if the flag is clear, the 
search direction is up. Initially, this flag 
specifies the state of the Up and Down 
buttons; after the user chooses the OK but- 
ton to close the dialog box, this flag speci- 
fies the user’s selection. | 


FR_ENABLEHOOK | | Enables the hook function specified in the 
IpfnHook member of this structure. This 
flag can be set on input. 


~ FR_ENABLETEMPLATE : Causes the system to use the dialog box 
: | template identified by the hInstance and 
IpTemplateName members to display the 
dialog box. This flag is used only to initial- 
ize the dialog box. . 


FR_ENABLETEMPLATEHANDLE Indicates that the hInstance member iden- 
| tifies a data block that contains a pre- 
loaded dialog box template. The system 
ignores the IlpTemplateName member if 
this flag is specified. This flag can be set 
| | on input. | 
FR_FINDNEXT . Indicates that the application should 
3 | | search for the next occurrence of the 
string specified by the IpstrFind What 
| member. This flag is set by the system. 
FR_HIDEMATCHCASE Hides and disables the Match Case check 
box. This flag can be set on input. 
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Value Meaning 


FR_HIDEWHOLEWORD Hides and disables the Match Only Whole 
Word check box. This flag can be set on 
— Input. | 
FR_HIDEUPDOWN Hides the Up and Down radio buttons that 


control the direction of searches through a 
document. This flag can be set on input. 


FR_MATCHCASE | Specifies that the search is to be case sen- 
| sitive. This flag is set when the dialog box 
is created and may be changed by the sys- 

tem in response to user input. 


FR_NOMATCHCASE Disables the Match Case check box. This 
| flag is used only to initialize the dialog 
box. 


FR_NOUPDOWN Disables the Up and Down buttons. This 
flag is used only to initialize the dialog 
box. 


FR_NOWHOLEWORD Disables the Match Whole Word Only 
| check box. This flag is used only to initial- 
ize the dialog box. 


FR_REPLACE _ Indicates that the application should re- 
| | _ place the current occurrence of the string 
specified in the IpstrFindWhat member 
with the string specified in the Ipstr- 
ReplaceWith member. This flag is set by 
the system. | 


FR_REPLACEALL Indicates that the application should 
7 replace all occurrences of the string 
specified in the IpstrFindWhat member 
with the string specified in the Ipstr- 
ReplaceWith member. This flag is set by 
the system. 

FR_SHOWHELP Causes the dialog box to show the Help 
button. If this flag is specified, the 
hwndOwner must not be NULL. This 
flag can be set on input. 


FR_WHOLEWORD | Checks the Match Whole Word Only 
| : | | check box. Only whole words that match - 
_ the search string will be considered. This 
flag is set when the dialog box is created 
and may be changed by the system in re- 
sponse to user input. 


IpstrFindWhat- | 
Specifies the string to search for. If a string is specified when the dialog box is 
created, the dialog box will initialize the Find What edit control with this string. 
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If the FR_LFINDNEXT flag is set when the dialog box is created, the application 
should search for an occurrence of this string (using the FR_DOWN, 
FR_WHOLEWORD, and FR_MATCHCASE flags to further define the direc- 
tion and type of search). The application must allocate a buffer for the string. 
This buffer should be at least 80 bytes long. This flag is set when the dialog box © 
is created and may be changed by the system in response to user input. 


IpstrReplace With | 
Specifies the replacement string for replace operations. The FindText function 
ignores this member. The ReplaceText function uses this string to initialize the 
Replace With edit control. This flag is set when the dialog box is created and 
may be changed by the system in response to user input. 


wFindWhatLen 
Specifies the length, in bytes, of the buffer to which oe IpstrFindWhat mem- 
ber points. This member is filled on input. 


wReplaceWithLen 
Specifies the length, in bytes, of the buffer to which the pete epee 
member points. This oe is filled on input. 


ICustData 
Specifies application-defined data that the system | passes to the hook function 
identified by the IpfnHook member. The system passes a pointer to the 
CHOOSECOLOR structure in the /Param parameter of the | 
WM_INITDIALOG message; this pointer can be used to retrieve the — 
_ ICustData member. 


IpfnHook 
Points to a hook function that processes messages intended for the 
dialog box. To enable the hook function, an application must specify the 
FR_ENABLEHOOK flag in the Flags member; otherwise, the system ignores 
this structure member. The hook function must return zero to pass a message 
that it didn’t process back to the dialog box procedure in COMMDLG.DLL. 
The hook function must return a nonzero value to prevent the dialog box proce-_ 
dure in COMMDLG.DLL from processing a message it has ay processed. 


This member is filled on input. 


_IpTemplateName 
Points to a null-terminated string that specifies the name of the resource file for 
_ the dialog box template that is to be substituted for the dialog box template in — 
COMMDLG.DLL. An application can use the MAKEINTRESOURCE macro | 
_ for numbered dialog box resources. This member is used only if the Flags mem- 
_ ber specifies the FR-ENABLETEMPLATE flag; otherwise, this member is ig- 
nored.. | 


This member is filled on input. 
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Comments | 


See Also 


FIXED 


Members 


Comments 


— See Also 


Some members of this structure are filled only when the dialog box is created, 
some are filled only when the user closes the dialog box, and some have an initiali- 
zation value that changes when the user closes the dialog box. Whenever a descrip- 
tion in the Members section does not specify how the value of a member is 
assigned, the value is assigned only when the dialog box is created. 


FindText, ReplaceText 


[3.1 | 


typedef struct tagFIXED { /* fx */ 
UINT fract; 
int value; 

} FIXED; 


The FIXED structure contains the integral and fractional parts of a fixed-point real 
number. | 


fract 
Specifies the fractional part of the number. 


value 
Specifies the integer part of the number. 


The FIXED structure is used to describe the elements of the MAT2 and 
POINTFX structures. 


GetGlyphOutline 
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FMS_GETDRIVEINFO 


‘Members 


See Also 


#Finclude <wfext.h> 


typedef struct tagFMS_GETDRIVEINFO { /* fmsgdi */ 
DWORD dwTotalSpace; 
DWORD dwFreeSpace; 
char szPath[260]; _ 
char. szVolume[14]; 
char szShare[128]; 
} FMS _GETDRIVEINFO, FAR *LPFMS GETDRIVEINFO; 


The FMS_GETDRIVEINFO structure contains information about the drive that 
is Selected in the currently active File Manager window. 


dwTotalSpace 
Specifies the total amount of storage space, in pyle on the disk associated with 
the drive. 


dwFreeSpace 7 7 
Specifies the amount of free slomage ae in bytes, « on the disk associated with 
the drive. . 


szPath | | 
Specifies a null- terminated string that contains the path of the current directory. 


sz Volume 


Specifies a null-terminated stritig that contains the volume label of the disk 
associated with the drive. — 


szShare | ae 
Specifies a null- feninated string that contains the name of the sharepoint (if 
the drive is being accessed through a network). 


FMExtensionProc, FM_GETDRIVEINFO- 
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FMS_GETFILESEL 


Members 


See Also 


deinclude <wfext.h> 


typedef struct tagFMS_GETFILESEL { /* fmsgfs */ 
UINT wlime; 
UINT wDate; 
DWORD dwSize; 
BYTE bAttr; 
char szName[260]; 


} FMS. GETFILESEL; 


The FMS_GETFILESEL structure contains information about a selected file in 


File Manager’s directory window or Search Results window. 


wlime 
Specifies the time when the file was created. 


| wDate 


Specifies the date when the file was created. 


dwSize | 
Specifies the size, in bytes, of the file. 


bAttr | 
Specifies the attributes of the file. 


szName 
Specifies a null-terminated string (an OEM string) that contains the fully- 
qualified path of the selected file. Before displaying this string, an extension 
should use the OemToAnsi function to convert the string to a Windows ANSI 
string. If a string is to be passed to the MS-DOS file system, an extension 
should not convert it. | | 


FMExtensionProc 
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FMS_ LOAD 


dtinclude <wfext.h> 


typedef struct tagFMS_ LOAD { /* fmsld */ 
DWORD dwSize; 
char szMenuName[MENU_TEXT_LEN]; 
HMENU hMenu; 
UINT wMenuDelta; 

} FMS_LOAD; 


The FMS_LOAD structure contains information that File Manager uses to add a 
custom menu provided by a File Manager extension dynamic-link library (DLL). 
The structure also provides a delta value that the extension DLL can use to 
manipulate the custom menu after File Manager has loaded the menu. 


Members 3 dwSize 
| Specifies the length of the structure, in bytes. 


szMenuName ) | 
Contains a null-terminated string for a menu item that appears in File 
Manager's main menu. . 3 


hMenu 
Identifies the pop-up menu that is added to File Manager's S main menu. 


wMenuDelta 
Specifies the menu-item delta value. To avoid conflicts with its own menu 
items, File Manager renumbers the menu-item identifiers in the pop-up menu 
identified by the hMenu member by adding this delta value to each identifier. 
An extension DLL that needs to modify a menu item must identify the item to 
modify by adding the delta value to the menu item’s identifier. The value of 
this member can vary from session to session. 


| See Also FMExtensionProc 
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GLOBALENTRY 


Members 


#Hinclude <toolhelp.h> 


typedef struct. tagGLOBALENTRY { /* ge */ 
DWORD dwSize; 
DWORD dwAddress; 
DWORD dwBlockSize; 
HGLOBAL hBlock; 
WORD wcLock; 
WORD wcPageLock; 
WORD wFlags; 
BOOL wHeapPresent; 
HGLOBAL hOwner; 
WORD wlype; 
WORD wData; 
DWORD dwNext; 
DWORD ~dwNextAlt; 

} GLOBALENTRY ; 


The GLOBALENTRY structure contains information about a memory object on 


the global heap. 


dwSize | 
Specifies the size of the GLOBALENTRY structure, in bytes. 


dwAddress 
Specifies the linear address of the global-memory object. 


dwBlockSize 
Specifies the size of the global- memory object, in bytes. 


hBlock 
Identifies the global-memory object. 


weLock | 
Specifies the lock count. If this value is zero, the memory object is not locked. 


wcPageLock 
Specifies the page lock count. If this value i is zero, the pen page is not 
locked. 


wFlags 
Specifies additional information about the memory object. This member can be 
the following value: : 


Value Meaning 


GF_PDB_OWNER The process data block (PDB) for the task is the owner of 
the memory object. 


wHeapPresent 
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Indicates whether a local heap exists within the sihbal: memory Ooi 


hOwner 


Identifies the owner of the global- -memory object. 


wType 


Specifies the memory type of the object. This type can be one of the following 


values: 
Value 


GT UNKNOWN 
GT_DGROUP 


GT_DATA 
GT_CODE 
_ GT_TASK 
GT_RESOURCE 


GT_MODULE 
GT_FREE 
GT_INTERNAL 
GT_SENTINEL 


GT _BURGERMASTER 


wData 


Meaning 
The memory type is not known. 


The object contains the default data segment and the 
stack segment. 


The object contains program data. (It may also contain 
stack and local heap data.) 


The object contains program code. If GT_CODE is 
specified, the wData member contains the segment 
number for the code. 


The object contains the task database. 


The object contains the resource type specified in 
wData. 


The object contains the module database. 


‘The object belongs to the free memory pool. 


The object is reserved for internal use by Windows. 
The object is either the first or the last object on the 
global heap. — 


The object contains a table that maps selectors to arena 
handles. © 


If the wl ype member is not GT_CODE or GT_ RESOURCE, wData i iS Zero. 


If wIype is GT_CODE, GT_DATA, or GT_DGROUP, wData contains the - 
segment number for the code. 


If wlype is G[_RESOURCE, wData specifies the ee of resource. The type 
can be one of the following values: 


Value 


GD_ACCELERATORS 


GD BITMAP | 


Meaning . 


The object contains data from the accelerator 
table. — | 


The object contains data describing a bitmap. 
This includes the bitmap color table and the bit- 
map bits. 
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See Also 


GLOBALENTRY 


Value 


GD_CURSOR 


GD_CURSORCOMPONENT 


GD_DIALOG 
GD_ERRTABLE 
GD_FONT 


GD_FONTDIR 
GD_ICON 


GD_ICONCOMPONENT 


GD_MENU 


GD_NAMETABLE 
GD_RCDATA 


GD_STRING 
GD_USERDEFINED 


dwNext 
Reserved for internal use by Windows. 


dwNextAlt 
Reserved for internal use by Windows. 


Meaning 


The object contains data describing a group of 
cursors. This includes the height, width, color 
count, bit count, and ordinal identifier for the cur- 
sors. 


The object contains data describing a single cur- 
sor. This includes bitmap bits and bitmasks for 
the cursor. 


The object contains data describing controls 
within a dialog box. 


The object contains data from the error table. 


The object contains data describing a single font. 
This data is identical to data in a Windows font 
file (.FNT). 


The object contains data describing a group of 
fonts. This includes the number of fonts in the re- 
source and a table of metrics for each of these 
fonts. 


The object contains data describing a group of 
icons. This includes the height, width, color 
count, bit count, and ordinal identifier for the 
icons. | 
The object contains data describing a single icon. 
This includes bitmap bits and bitmaps for the 
icon. 

The object contains menu data for normal and 
pop-up menu items. . 

The object contains data from the name table. 
The object contains data from a user-defined re- 
source. | 
The object contains data from the string table. 


The resource has an unknown resource identifier 
or is an application-specific named type. 


| GlobalEntryHandle, GlobalEntryModule, GlobalFirst, GlobalNext, 
GLOBALINFO 


 GLYPHMETRICS 297 


GLOBALINFO aa] 


#tinclude <toolhelp.h> 


typedef struct tagGLOBALINFO { /* gi */ 
DWORD dwSize; 
WORD wceclItems; 
WORD wcItemsFree; 
WORD wcItemsLRU; 
} GLOBALINFO; 


The GLOBALINFO structure contains information about the global heap. 


Members dwSize 
Specifies the size of the GLOBALINFO structure, in bytes. 


wcltems 
_ Specifies the total number of items on the global heap. 


wcltemsFree | 
Specifies the number of free items on the global heap. 


weltemsLRU 
Specifies the number of “least ey used” (LRU) items on the global heap. 


See Also GlobalInfo, GLOBALENTRY 


GLYPHMETRICS Pa | 


typedef struct tagGLYPHMETRICS { /* gm */ 
UINT gmBlackBoxx; 
UINT gmBlackBoxyY; 
POINT gmptGlyphOrigin; 
int gmCellIncx; 
int gmCelliIncy; 
} GLYPHMETRICS; 


The GLYPHMETRICS structure contains information about the pce and 
orientation of a glyph in a character cell. 


Members emBlackBoxX | 
Specifies the width of the smallest rectangle that completely oo the glyph 
(its “black box”). 
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gmBlackBoxY 
Specifies the height of the smallest poctalig ie that completely encloses the ee 
(its “black box’”’). 

emptGlyphOrigin 
Specifies the x- and y-coordinates of the upper-left corner of the smallest 
rectangle that completely encloses the glyph. 


emCellIncX 
Specifies the horizontal distance from the origin of the current character cell to 
the origin of the next character cell. 


gemCellIncY 
Specifies the vertical distance from the origin of the current character cell to the 
origin of the next character cell. 


Comments Values in the GLYPHMETRICS structure are specified in logical units. 


See Also GetGlyphOutline 


-HANDLETABLE rox] 


typedef struct tagHANDLETABLE { /* ht */ 
HGDIOBJ objectHandle[1]; 
} HANDLETABLE; 


The HANDLETABLE structure is an array of handles, each of which identifies a 
graphics device interface (GDI) object. 


Members objectHandle 
Contains an array of handles. 


See Also EnumMetaFile, PlayMetaFileRecord | 
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HARDWAREHOOKSTRUCT Ex 


Members 


HELPWININFO 


typedef struct tagHARDWAREHOOKSTRUCT { /* hhs */ 


HWND hWnd; 
UINT wMessage; 
WPARAM wParam; 
LPARAM 1Param; 

} HARDWAREHOOKSTRUCT ; 


The HARDWAREHOOKSTRUCT contains information about a hardware mes- 
sage placed in the system message queue. | 


hWnd 
Identifies the window that will receive the message. 


wMessage 
Specifies the message identifier. 


wParam are 7 ; 
Specifies additional information about the message. The exact meaning de- 
pends on the wMessage parameter. 


IParam : 
Specifies additional information about the message. The exact meaning de- 
pends on the wMessage parameter. 


typedef struct { 

int wStructSize; 

int x; 

int y; 

int dx; 

int dy; 

int wMax; 

char rgchMember[2]; 
} HELPWININFO; 


The HELPWININFO structure contains the size and position of a secondary help 
window. An application can set this size by calling the WinHelp function with the 
HELP_SETWINPOS value. 
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Members 


Comments 


See Also 


wstructSize : a 
Specifies the size of the HELPWININFO structure. 


x | 
Specifies the x-coordinate of the upper-left corner of the window. 


Specifies the y-coordinate of the upper-left corner of the window. 


dx 
Specifies the width of the window. | 


dy | 
Specifies the height of the window. 


wMax | 
Specifies whether the window should be maximized or set to the given position 
and dimensions. If this value is 1, the window is maximized. If it is zero, the 
size and position of the window are determined by the x, y, dx, and dy mem- 
bers. 


rgchMember 
Specifies the name of the window. 


Microsoft Windows Help divides the display into 1024 units in both the x- and y- 
directions. To create a secondary window that fills the upper-left quadrant of the 
display, for example, an application would specify zero for the x and y members 
and 512 for the dx and dy members. 


WinHelp 


HSZPAIR 


Members 


KERNINGPAIR 


Members 


See Also 
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#include <ddeml.h> 


typedef struct tagHSZPAIR { /* hp */ 
~HSZ hszSve; 
HSZ hszTopic; 
} HSZPAIR; 


The HSZPAIR structure contains a dynamic data exchange (DDE) service name 
and topic name. A DDE server application can use this structure during an 
XTYP_WILDCONNECT transaction to enumerate the lad a name pairs 
that it supports. 


hszSvc 
Identifies a service name. 


hszTopic 
Identifies a topic name. 


typedef struct tagKERNINGPAIR { 
WORD wFirst; 
WORD wSecond; 
int  ikKernAmount; 

} KERNINGPAIR; 


The KERNINGPAIR structure defines a kerning pair. | 


wFirst 
Specifies the character code for the first ey in the kerning pair. 


wSecond 
Specifies the character code for the second character i in the kerning pair. 


iKernAmount | 
Specifies the amount that this pair will be kerned if they appear side by side in 
the same font and size. This value is typically negative, because pair-kerning 
usually results in two characters being set more tightly than normal. The value 
is given in logical units—that is, it depends on the current mapping mode. 


GetKerningPairs 
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LOCALENTRY 


Members 


#Finclude <toolhelp.h> 


typedef struct tagLOCALENTRY { /* le */ 
DWORD = dwSize; 
HLOCAL hHandle; 
WORD wAddress; 
WORD wSize; 
WORD wFlags; 
WORD wcLock; 
WORD wlype; 
WORD hHeap; 
WORD wHeaplype; 
WORD wNext; 

} LOCALENTRY; 


The LOCALENTRY structure contains information about a memory object on 
the local heap. | | 


dwSize 
Specifies the size of the LOCALENTRY structure, in bytes. 


hHandle 
_ Identifies the local-memory object. 


wAddress 
Specifies the address of the local-memory object. 


wsize 
Specifies the size of the local-memory object, in bytes. 


wFlags | 


Specifies whether the memory object is fixed, free, or movable. This member 
can be one of the following values: | : 


Value Meaning 
LF_FIXED The object resides in a fixed memory location. — 
LF_FREE The object is part of the free memory pool. 


LF.-MOVEABLE The object can be moved in order to compact memory. 


weLock | | 
Specifies the lock count. If this value is zero, the memory object is not locked. 


wlype 


LOCALENTRY 
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Specifies the content of the HINO, object. This member can be one of the fol- 


lowing values: 
Value 


LT_FREE 
LT_GDI_BITMAP 
LT_GDI_BRUSH 
LT_GDI_DC 
LT_GDI_DISABLED_DC 
LT_GDI_FONT 
LT_GDI_MAX 
LT_GDI_METADC 
LT_GDI_METAFILE 
LT_GDI_PALETTE 
LT_GDI_PEN 
LT_GDI_RGN 
LT_NORMAL 

~ LT_USER_ATOMS 
LT_USER_BWL | 
LT_USER_CBOX 

_ LT_USER_CHECKPOINT 
LT_USER_CLASS 
LT_USER_CLIP 
LT_USER_DCE 

-LT_USER_ED 
LT_USER_HANDLETABLE 


LT_USER_HOOKLIST 
LT_USER_HOTKEYLIST 
LT_USER_LBIV 


Meaning 


The object belongs to the free memory pool. 
The object contains a bitmap header. 

The object contains a brush. 

The object contains a device context. 


The object is reserved for internal use by Windows. 


The object contains a font header. 


The object is reserved for internal use by Windows. 


The object contains a metafile device context. 
The object contains a metafile header. 

The object contains a palette. 

The object contains apen. 

The object contains a region. 


The object is reserved for internal use by Windows. 
The object contains an atom structure. 
The object is reserved for internal use by Windows. 


The object contains a combo-box structure. 


The object is reserved for internal use by no: 


The object contains a class structure. 


The object is reserved for internal use by Windows. 
The object is reserved for internal use by Windows. 


The object contains an edit-control structure. 


The object is reserved for internal use by Windows. 
The object is reserved for internal use by Windows. 
The object is reserved for internal use by Windows. 


The object contains a list-box structure. 


LT_USER_LOCKINPUTSTATE 


LT_USER_MENU 
LT_USER_MISC 
LT_USER_MWP | 
LT_USER_OWNERDRAW 
LT_USER_PALETTE 

_ LT_USER_POPUPMENU 
LT_USER_PROP 


The object is reserved for internal use by Windows. 


The object contains a menu structure. 


The object is reserved for internal use by Windows. 
The object is reserved for internal use by Windows. 
The object is reserved for internal use by Windows. 
The object is reserved for internal use by Windows. 
The object is reserved for internal use by Windows. 


The object contains a window-property structure. 
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Comments 


See Also 


Value 2% = Meaning 


LT_USER_SPB | The object is reserved for internal use by Windows. 
LT_USER_STRING The object is reserved for internal use by Windows. 


LT —USER_ USERSEEUSERDOALLOC 
The object is reserved for internal use by Windows: 


LT_USER_WND The object contains a window structure. 
hHeap 
Identifies the ieeal: -memory heap. 
wHeapType 
Specifies the type of local heap. This type can be one of the following values: 
Value Meaning 
NORMAL_HEAP The heap is the default heap. 
USER_HEAP The heap is used by the USER module. 
GDI_HEAP The heap is used by the GDI module. 
wNext 


Specifies the next entry in the local HEAD: This member is reserved for internal 
use by Windows. 


The ee values are for informational purposes only. Microsoft reserves the 
right to change or delete these tags at any time. Applications should never directly 
change items on the system heaps, as this information will change in future ver- 
sions. The wType values for the USER module are included only in the debugging 
versions of USER.EXE. 


LocalFirst, LocalNext, LOCALINFO 


LOCALINFO 


Members" 


See Also 


LOGBRUSH 


- Members 
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include <toolhelp.h> 


typedef struct tagLOCALINFO { /* li */ 
DWORD dwSize; 
WORD wclItems; 

} LOCALINFO; 


The LOCALINFO structure contains information about the local heap. 


dwSize 
Specifies the size of the LOCALINFO structure, in bytes. 


wcltems 
Specifies the total number of items on the local heap. 


-LocalInfo, LOCALENTRY 


typedef struct tagLOGBRUSH { /* 1b */ 


UINT 1bStyle; 

COLORREF 1bColor; 

int lTbHatch; 
} LOGBRUSH; 


The LOGBRUSH structure defines the style, color, and pattern of a physical 
brush to be created by using the CreateBrushIndirect function. 


IbStyle 


Specifies the brush style. This member can be one of the following values: 
Value | Meaning 


| BS_DIBPATT ERN Specifies a pattern brush defined by a device-independen 
| : bitmap (DIB) specification. 


| BS_HATCHED Specifies a hatched brush. 


_BS_HOLLOW Specifies a hollow brush. _ 
BS_PATTERN | Specifies a pattern brush defined by a memory bitmap. 
BS_NULL ' Equivalent to BS_HOLLOW. _ 


BS_SOLID _ Specifies a solid brush. 
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LOGBRUSH 


See Also 


IbColor 


Specifies the color in which the brush is to be drawn. If the IbStyle member is 
the BS_HOLLOW or BS_PATTERN value, IbColor is ignored. 


If IpStyle is the BS_DIBPATTERN value, the low-order word of IbColor 
specifies whether the bmiColors members of the BITMAPINFO structure con- 
tain explicit RGB values or indexes into the currently realized logical palette. 
The IbColor member must be one of the following values: 


Value Meaning 


DIB_PAL_ COLORS Color table consists of an array of 16-bit indexes into the 
currently realized logical palette. 


DIB_RGB_COLORS Color table contains literal RGB values. 


lIbHatch 


Specifies a hatch style. The meaning depends on the brush style. 


If the IbStyle member is the BS_DIBPATTERN style, the IbHatch member 
contains a handle to a packed DIB. To obtain this handle, an application calls 
the GlobalAlloc function to allocate a global memory object and then fills the 
memory with the packed DIB. A packed DIB consists of a BITMAPINFO 
structure immediately followed by the array of bytes which define the pixels of 


the bitmap. 


If the IbStyle member is the BS “HATCHED style, the IbHatch member speci- 
fies the orientation of the lines used to create the ae This member can be 
one of the following values: 


Value | Meaning 

HS_BDIAGONAL 45-degree upward hatch (left to right) 
HS_CROSS Horizontal and vertical cross-hatch 
HS_DIAGCROSS — 45-degree cross-hatch 


HS_FDIAGONAL 45-degree downward hatch (left to right) 
HS_HORIZONTAL Horizontal hatch 
HS_VERTICAL Vertical hatch 


if the IbStyle member is the BS_PATTERN wie IbHatch must be a handle to 
the bitmap that defines the pattern. 


If the IbStyle member is the BS_SOLID or the BS ~HOLLOW style, IbHatch 
1S ignored. 


BITMAPINEFO, CreateBrushIndirect, CreateBrushIndirect, GlobalAlloc | 


LOGFONT 


Members 
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ny 


typedef struct tagLOGFONT { /* |f */ 

int 1fHeight; 

int 1fWidth; 

int -lfEscapement; 

int 1fOrientation; 

int lfWeight; 

BYTE 1fiItalic; 

BYTE 1lfUnderline; 

BYTE 1fStrikeQOut; - 

BYTE 1fCharSet; 

BYTE 1IfOutPrecision; 

BYTE 1fClipPrecision; 

BYTE 1fQuality; 

BYTE IfPitchAndFamily; 

BYTE 1fFaceName[LF_FACESIZE]; 
} LOGFONT; 


The LOGFONT structure defines the attributes of a font, a drawing object used to 
write text on a display surface. 


IfHeight 
Specifies the desired height, in logical units, for the font. If this value is greater 
than zero, it specifies the cell height of the font. If itis less than zero, it speci- 
fies the character height of the font. (Character height is the cell height minus 
the internal leading. Applications that specify font height in points typically use 
a negative number for this member.) If this value is zero, the font mapper uses a 
default height. The font mapper chooses the largest physical font that does not 
exceed the requested size (or the smallest font, if all the fonts exceed the re- 
quested size). The absolute value of the IfHeight member must not exceed 
16,384 after it is converted to device units. 


lfWidth 
Specifies the average width, in logical units, of characters in the font. If this 
value is zero, the font mapper chooses a reasonable default width for the 
specified font height. (The default width is chosen by matching the aspect ratio 
of the device against the digitization aspect ratio of the available fonts. The 
closest match is determined by the absolute value of the difference.) The widths 
of characters in TrueType fonts are scaled by a factor of this member divided 

by the width of the characters in the physical font (as specified by the © 

tmAveCharWidth member of the TEXTMETRIC structure). 


IfEscapement : 
Specifies the angle, in tenths of eae between the base line of a character 
and the x-axis. The angle is measured in a counterclockwise direction from the 
x-axis for left-handed coordinate systems (that is, MM_TEXT, in which the y 
direction is down) and in a clockwise direction from the x-axis for right-handed | 
~ coordinate systems (in which the y direction is up). 
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lfOrientation | 
Specifies the orientation of the characters. This value is ignored. 

IfWeight 7 
Specifies the font weight. This member can be one of the following values: 
Constant Value 
FW_DONTCARE 0 
FW_THIN 100 


FW_EXTRALIGHT 200 
FW_ULTRALIGHT 200 


FW_LIGHT 300 
FW_NORMAL 400 
FW_REGULAR 400 
FW_MEDIUM 500 
FW_SEMIBOLD 600 
FW_DEMIBOLD 600 
FW_BOLD 700 


FW_EXTRABOLD 800 
FW_ULTRABOLD 800 
FW_BLACK 900 
FW_HEAVY 900 | 


The actual appearance of the font depends on the type face. Some fonts 
have only FW_NORMAL, FW_REGULAR, and FW_BOLD weights. If 
FW_DONTCARE is specified, a default weight is used. 


IfItalic 
Specifies an italic font if nonzero. 

IfUnderline 

_ Specifies an underlined font if nonzero. | 

lfStrikeOut | 

Specifies a strikeout font if nonzero. | 
‘iIfCharSet | | 

Specifies the character set of the font. The following values are predefined: 
Constant | Value 
ANSI_CHARSET 0 


DEFAULT_CHARSET 1 
SYMBOL_CHARSET 2 
SHIFTJIS_CHARSET 128 
OEM_CHARSET 255 
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The DEFAULT_CHARSET value is not used by the font mapper. An applica- 
tion can use this value to allow the name and size of a font to fully describe the 
logical font. If the specified font name does not exist, a font from any character 
set can be substituted for the specified font; applications should use the 
DEFAULT_CHARSET value sparingly to avoid unexpected results. 


The OEM character set is system-dependent. 


Fonts with other character sets may exist in the system. If an application uses a 
font with an unknown character set, it should not attempt to translate or inter- 
pret strings that are to be rendered with that font. 

IfOutPrecision — | 
Specifies the desired output precision. The output precision defines how closely 
the output must match the height, width, character orientation, escapement, and 
pitch of the requested font. This member can be one of the following values: 


OUT_CHARACTER_PRECIS OUT_STRING_PRECIS 


OUT_DEFAULT_PRECIS | OUT_STROKE_PRECIS _ 
OUT_DEVICE_PRECIS OUT_TT_PRECIS 


OUT_RASTER_PRECIS OUT_TT_ONLY_PRECIS 


Applications can use the values OUT_DEVICE_PRECIS, 
OUT_RASTER_PRECIS, and OUT_TT_PRECIS to control how the 
font mapper chooses a font when the system contains more than one font 

with a given name. For example, if a system contains a font named “Symbol” 
in raster and TrueType form, specifying OUT_TT_PRECIS would force the 
font mapper to choose the TrueType version. (Specifying OUT_TT_PRECIS 
forces the font mapper to choose a TrueType font whenever the specified font. 
name matches a device or raster font, even when there is no TrueType font with 
the same name.) 


An application can use TrueType fonts exclusively by specifying 
OUT_TT_ONLY_PRECIS. When this value is specified, the system 
chooses a TrueType font even when the name specified 1 in the IffaceName 
member matches a raster or vector font. 


ifClipPrecision 
Specifies the desired clipping precision. The clipping precision defines how to 
clip characters that are partially outside the clipping region. This member can 
be any one of the following values: 


CLIP_CHARACTER_PRECIS CLIP_MASK > 
CLIP_DEFAULT_PRECIS _ CLIP_STROKE_PRECIS 
(CLIPLEMBEDDED ee 
CLIP_ LH_ANGLES | 7 


To use an Secs read-only font, applications must specify the 


CLIP_EMBEDDED value. 


To achieve consistent rotation of device, TrueType, and vector fonts, an applica- 
tion can use the OR operator to combine the CLIP_LLH_ANGLES value with 
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any of the other IfClipPrecision values. If the CLIP_LH_ANGLES bit is set, 

the rotation for all fonts is dependent on whether the orientation of the coordi- 
nate system is left-handed or right-handed. If CLIP_LH_ANGLES is not set, 
device fonts always rotate counter-clockwise, but the rotation of other fonts is 
dependent on the orientation of the coordinate system. (For more information 
about the orientation of coordinate systems, see the description of the 
IfEscapement member.) 


IfQuality 
Specifies the output quality of the font, which defines how carefully the 
graphics device interface (GDI) must attempt to match the logical-font 
attributes to those of an actual physical font. This member can be one of the 
following values: | 


Value Meaning 
DEFAULT_QUALITY Appearance of the font does not matter. 
DRAFT_QUALITY Appearance of the font is less important than when the 


PROOF_QUALITY value is used. For GDI raster fonts, 
scaling is enabled. Bold, italic, underline, and strikeout 
fonts are synthesized if necessary. 

PROOF_QUALITY = — Character quality of the font is more important than 
exact matching of the logical-font attributes. For GDI 
raster fonts, scaling is disabled and the font closest in 
size is chosen. Bold, italic, underline, and strikeout 
fonts are synthesized if necessary. 


IfPitchAndF amily 
Specifies the pitch and family of the font. The two low-order bits, which 
specify the pitch of the font, can be one of the following values: 


DEFAULT_PITCH 
FIXED_PITCH | 
VARIABLE_PITCH 


The four high-order bits of the member, which specify the font eat, can be 
one of the following values: 


Value _ Meaning 

FF_DECORATIVE Novelty fonts. Old English is an example. 

FF_DONTCARE Don’t care or don’t know. 

FF_MODERN Fonts with constant stroke width, with or without serifs. 
| Pica, Elite, and Courier New® are examples. 

FF_ROMAN Fonts with variable stroke width and with serifs. Times 


New Roman® and New Century Schoolbook® are ex- 
amples. 
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Value | Meaning 

FF_SCRIPT | Fonts designed to look like handwriting. Script and Cursive 
| are examples. 

FF_SWISS Fonts with variable stroke width and without serifs. 


MS® Sans Serif is an example. 


An application can specify a value for the lfPitchAndFamily member by using 
the Boolean OR operator to join a pitch constant with a family constant. 


Font families describe the look of a font in a general way. They are intended for — 
specifying fonts when the exact typeface desired is not available. 


IffaceName 
Specifies the typeface name of the font. The length of this string must not 
exceed LF_FACESIZE — 1. The EnumFontFamilies function can be used to 
enumerate the typeface names of all currently available fonts. If lfFaceName is 
NULL, GDI uses a device-dependent typeface. 


Comments AppiicNions & can use the default settings for most of these members when creating 
a logical font. The members that should always be given specific values are | 
IfHeight and IfFaceName. If lfHeight and IfFaceName are not set by the applica- 
tion, the logical font that is created is device-dependent. 


See Also CreateFontIndirect, EnumFontFamilies 


LOGPALETTE 
typedef struct tagLOGPALETTE { /* lgpl */ 
WORD palVersion; 
WORD palNumEntries; 
PALETTEENTRY palPalEntry[1]; 
} LOGPALETTE; 


~ The LOGPALETTE structure defines a logical color palette. 


Members palVersion 7 
| 7 Specifies the Windows version number for the structure. This value should be 
0x300 for Windows 3.0 and later. 


palNumEntries. 
Specifies the number of palet color entries. 


palPalEntry 
ae an array of PALETTEENTRY structures that define the color and. 
usage of each entry in the logical palette. 
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Comments 


See Also 


LOGPEN 


Members 


The colors in the palette entry table should appear in order of importance, because 
entries earlier in the logical palette are most likely to be placed in the system 
palette. 


This structure is passed as a parameter to the CreatePalette function. 


CreatePalette, PALETTEENTRY 


typedef struct tagLOGPEN { /* lgpn */ 


UINT lopnStyle; 

POINT lopnWidth; 

COLORREF lopnColor; 
} LOGPEN; | 


The LOGPEN structure defines the style, width, and color of a pen, a drawing ob- 
ject used to draw lines and borders. The CreatePenIndirect function uses the 
LOGPEN structure. 


lopnStyle 
Specifies the pen type. This member can be one of the following values: 
Value Meaning 
PS_SOLID Creates a solid pen. 
PS_DASH Creates a dashed pen. (Valid only when the pen width is 1.) 
PS_DOT Creates a dotted pen. (Valid only when the pen width is 1.) 
PS_DASHDOT Creates a pen with alternating dashes and dots. (Valid only 


when the pen width is 1.) 


PS_DASHDOTDOT Creates a pen with alternating dashes and double dots. 
(Valid only when the pen width is 1.) 


PS_NULL Creates a null pen. 


PS_INSIDEFRAME Creates a pen that draws a line inside the frame of closed 

/ shapes produced by graphics device interface (GDI) out- 
put functions that specify a bounding rectangle (for ex- 
ample, the Ellipse, Rectangle, RoundRect, Pie, and 
Chord functions). When this style is used with GDI out- 
put functions that do not specify a bounding rectangle (for 
example, the LineTo function), the drawing area of the 
pen is not limited by a frame. 


Comments 


See Also 


MAT2 


Members 


MAT2 313. 


If a pen has the PS_INSIDEFRAME style and a color that does not match a 
color in the logical color table, the pen is drawn with a dithered color. The 
PS_SOLID pen style cannot be used to create a pen with a dithered color. The 
PS_INSIDEFRAME style is identical to PS_SOLID if the pen width is less 
than or equal to 1. 


When the PS_INSIDEFRAME see] is used with GDI objects produced by 
- functions other than Ellipse, Rectangle, and RoundRect, the line may not be 
completely inside the specified frame. 


lopnWidth 
Specifies the pen width, in logical units. If the lopnWidth member is zero, the 
pen is One pixel wide on raster devices regardless of the current mapping mode. 


lopnColor 
Specifies the pen colar. 


The y value in the POINT structure for the lopnWidth member is not used. 


CreatePenIndirect, POINT 


typedef struct tagMAT2 { /* mat2 */ 
FIXED eM11; 
FIXED eM12; 
FIXED eM21; 
FIXED eM22; 
} MAT2; 


The MAT2 structure contains the values for a transformation matrix. 


eM11 
Specifies a fixed-point value for the M// component of a 2 Dby. -2 transformation 


‘matrix. 


eM12 , | | 

Specifies a fixed-point value for the M12 component of a 2-by-2 transformation 
matrix. 

eM21 
Specifies a fixed-point value for the M21 component of a 2-by-2 transformation 
matrix. 
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Comments 


See Also 


MDICREATESTRUCT 


Members 


eM22 | | 
Specifies a fixed-point value for the M22 component of a 2-by-2 transformation 
matrix. 


The identity matrix produces a transformation in which the transformed graphical 
object is identical to the source object. In the identity matrix, the value of eM11 is 
1, the value of eM12 is zero, the value of eM21 is zero, and the value of eM22 is 1. 


GetGlyphOutline 


typedef struct tagMDICREATESTRUCT { /* mdic */ 
LPCSTR szClass; | 
LPCSTR szlTitlie; 
HINSTANCE hOwner; 


int ms 
int. _ Ne 

int CX; 
int Cy; 
DWORD style; 


LPARAM 1Param; 
} MDICREATESTRUCT; 


The MDICREATESTRUCT structure contains information about the class, title, 
owner, location, and size of a multiple document interface (MDI) child window. 


szClass oO | | 
Contains a long pointer to the application-defined class of the MDI child win- 
dow. 3 3 


szTitle | 
Contains a long pointer to the window title of the MDI child window. 


hOwner : | 
Identifies the instance handle of the application creating the MDI child window. 


4 See ee | es 

Specifies the initial position of the left side of the MDI child window. If this 
member is set to CW_USEDEFAULT, the MDI child window is assigned a de- 
fault horizontal position. 
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Specifies the initial position of the top edge of the MDI child window. If this 
member is set to CW_USEDEFAULT, the MDI child window is assigned a de- 
fault vertical position. 
cx 
Specifies the initial width of the MDI child window. If this member is set to 
~ CW_USEDEFAULT, the MDI child window is assigned a default width. 
cy 
Specifies the initial height of the MDI child window. If this member is set to 
CW_USEDEFAULT, the MDI child window is assigned a default height. 
style | 
Specifies additional styles for the MDI child window. If the window was 
created with the MDIS_ALLCHILDSTYLES window style, the style member © 
may be any combination of the window styles documented with the 
CreateWindow function. Otherwise, it may be one or more of the following 
values: | 


Value Meaning 


WS_MINIMIZE MDI child window is created in a minimized state. 
WS_MAXIMIZE MDI child window is created in a maximized state. — 
WS_HSCROLL MDI child window is created with a horizontal scroll bar. 
WS_VSCROLL — MDI child window is created with a vertical scroll bar. 


lParam 
Specifies an application-defined 32-bit value. 


Comments “When the MDI child window is created, Windows sends the WM_CREATE 
message to the window. The /Param parameter of the WM_CREATE message 
contains a pointer to a CREATESTRUCT structure. The IlpCreateParams mem- 
ber of CREATESTRUCT contains a pointer to the MDICREATESTRUCT 
structure passed with the WM_MDICREATE message that created the MDI child 
window. 


See Also _ CREATESTRUCT 
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MEASUREITEMSTRUCT 


Members 


typedef struct tagMEASUREITEMSTRUCT { /* mi */ 
UINT  CtlType; 
 UINT  CtlTID; 
UINT itemID; 
UINT jtemWidth; 
UINT itemHeight; 
DWORD itemData; 
} MEASUREITEMSTRUCT; 


The MEASUREITEMSTRUCT structure informs Windows of the dimensions 
of an owner-drawn control. This allows Windows to process user interaction with 


the control correctly. The owner of an owner-drawn control receives a pointer to 


this structure as the /Param parameter of an WM_MEASUREITEM message. The 
owner-drawn control sends this message to its owner window when the control is 
created. The owner then fills in the appropriate members in the structure for the 
control and returns. This structure is common to all owner-drawn controls. 


CtlType 
Specifies the control type. The values for control types are as follows: 
Value : Meaning 
ODT_BUTTON Owner-drawn button 
ODT_COMBOBOX Owner-drawn combo box 
ODT_LISTBOX Owner-drawn list box 
ODT_MENU Owner-drawn menu 
CtlID 


Specifies the control identifier for a combo box, list box, or button. This mem- 
ber 1s not used for a menu. 


itemID — 
Specifies the menu-item identifier for a menu or the list-box item identifier for 
a variable-height combo box or list box. This member is not used for a fixed- 
height combo box or list box or for a button. sa 


item Width | 
Specifies the width of a menu item. The owner of the owner-drawn menu item - 
must fill this member before returning from the message. 


itemHeight | 
Specifies the height of an individual item in a list box or a menu. Before return- 
ing from the message, the owner of the owner-drawn combo box, list box, or 
menu item must fill out this member. The maximum height of a list box item is 
255; . | | 
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itemData 
Contains the value that was passed to the e6inbe box or list box in the [Param 
parameter of one of the following messages: 


CB_ADDSTRING 
CB_INSERTSTRING 
LB_ADDSTRING 
LB_INSERTSTRING 


Comments Failure to fill out the proper members in the MEASUREITEMSTRUCT struc- 
ture will cause improper operation of the control. 


MEMMANINFO oad 


#Hinclude <toolhelp.h> 


typedef struct tagMEMMANINFO { /* mmi */ 
DWORD dwSize; 
DWORD dwLargestFreeBlock; 
DWORD dwMaxPagesAvai lable; 
DWORD dwMaxPagesLockable; 
DWORD dwTotalLinearSpace; 
DWORD dwTotalUnlockedPages; 
DWORD dwFreePages; 
DWORD dwlotalPages; 
DWORD dwFreeLinearSpace; 
DWORD dwSwapFilePages; 
WORD wPageSize; 

} MEMMANINFO; 


The MEMMANINFO structure contains information about the status and per- 
formance of the virtual-memory manager. If the memory manager is running in 
standard mode, the only valid member of this structure is the dwLargestFree- 
Block member. 


Members — dwSize 
Specifies the size of the MEMMANINEFO structure, in bytes. 


_ dwLargestFreeBlock 
Specifies the largest free block of contiguous linear memory in the system, in 
bytes. 


dwMaxPagesAvailable _ | 
Specifies the maximum number of pages that éould be allocated in the system 
_ (the value of dwLargestFreeBlock divided by the value of wPageSize). 
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| See Also 


MENUITEMTEMPLATE 


Members 


dwMaxPagesLockable 
Specifies the maximum number of pages that could be allocated and locked. 


dwTotalLinearSpace 
Specifies the size of the total linear addréss space, in Pages. 


dwTotalUnlockedPages 
Specifies the number of unlocked pages in the system. This value includes fee 


pages. 
dwFreePages 
Specifies the number of pages that are not in use. 


dwTotalPages 
Specifies the total number of pages the virtual-memory manager manages. This 
value includes free, locked, and unlocked pages. 


dwFreeLinearSpace 
Specifies the amount of free memory in the linear address space, in pages. 


dwSwapFilePages 
Specifies the number of pages in the system swap file. 


wPageSize 
Specifies the system page size, in bytes. 


MemMantInfo 


typedef struct { /* mit */ 
UINT mtOption; | 
UINT mtID; 
char mtString[1]; 

} MENUTTEMTEMPLATE; 


| The MENUITEMTEMPLATE structure defines a menu item. 


mtOption 
Specifies a mask of one or more predefined menu options that specify the 
appearance of the menu item. The menu options follow: 


Value  — Meaning 
MF_CHECKED Item has a check mark next to it. : 
MF_GRAYED Item is initially inactive and drawn with a gray effect. 


MF_HELP Item has a vertical separator to its left. 
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Value Meaning | 
_ MF_MENUBARBREAK Item is placed in a new column. The old and new. 
columns are separated by a bar. 
MF_MENUBREAK Item is placed in a new column. 


MF_OWNERDRAW Owner of the menu is responsible for drawing all 
visual aspects of the menu item, including 
highlighted, checked and inactive states. This option 
is not valid for a top-level menu item. 


MF_POPUP Item displays a sublist of menu items when selected. 


~mtID 
Specifies an ‘dcntiieation code for a non- 1-pop- up menu item. The MENU-_ 
ITEMTEMPLATE structure for a pop-up menu item does not contain the 
mtID member. 


mtString 
mpeeines a null-terminated string that contains the name of the menu item. 


See Also : LoadMenulIndirect, MENUITEMTEMPLATEHEADER 


MENUITEMTEMPLATEHEADER (a) 


typedef struct { /* mith */ 
UINT versionNumber; 
UINT offset; 

} MENUITEMTEMPLATEHEADER; 


A complete menu template consists of a header and one or more menu-item lists. 


Members ; versionNumber 
Specifies the version number. This member should be zero. 
offset 
_ Specifies the offset from the end of the header, in oe where the menu-item 
list begins. 


Comments One or more MENUITEMTEMPLATE structures are combined to form the 
| menu-item list. 


See Also MENUITEMTEMPLATE 
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METAFILEPICT 


typedef struct tagMETAFILEPICT {  /* mfp */ 


int mm; 
int XExt; 
int yExt; 


HMETAFILE hMF; 


} METAFILEPICT; 


The METAFILEPICT structure defines the metafile picture format used for ex- 
changing metafile data through the clipboard. 


Members mm 


Specifies the mapping mode in which the picture is drawn. 


xExt 


Specifies the size of the metafile picture for all modes except the 
MM_ISOTROPIC and MM_ANISOTROPIC modes. The x-extent 
specifies the width of the rectangle within which the picture is drawn. 
The coordinates are in units that correspond to the mapping mode. 


yExt 


Specifies the size of the metafile picture for all modes except the 
MM_ISOTROPIC and MM_ANISOTROPIC modes. The y-extent 
specifies the height of the rectangle within which the picture is drawn. 
The coordinates are in units that correspond to the mapping mode. 


For MM_ISOTROPIC and MM_ANISOTROPIC modes, which can be’ 

scaled, the xExt and yExt members contain an optional suggested size in 
MM_HIMETRIC units. For MM_ANISOTROPIC pictures, xExt and yExt can 
be zero when no suggested size is supplied. For MM_ISOTROPIC pictures, an 


_ aspect ratio must be supplied even when no suggested size is given. (If a sug- 
- gested size is given, the aspect ratio is implied by the size.) To give an aspect 
ratio without implying a suggested size, set xExt and yExt to negative values 


whose ratio is the appropriate aspect ratio. The magnitude of the negative xExt 
and yExt values will be ignored; only the ratio will be used. 


hMF 


Identifies a memory metafile. 


See Also SetClipboardData 
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typedef struct tagMETAHEADER { /* mh */ 
UINT mtType; 
UINT mtHeaderSize; 
UINT mtVersion; 
DWORD mtSize; 
UINT mtNoObjects; 
DWORD mtMaxRecord; - 
UINT mtNoParameters; 
} METAHEADER; 


The METAHEADER structure contains information about a metafile. 


_ Members mtType 7 
| Specifies whether the metafile is in memory or recorded in a disk file. This 
member can be one of the following values: 


Value Meaning 

1 Metafile is in memory. 

2 Metafile is in a disk file. 
mtHeaderSize 


Specifies the size, in words, of the metafile header. 


mtVersion 
Specifies the Windows version number. The version annibee for metafiles that 
support device-independent bitmaps (DIBs) i is Ox0300. Otherwise, the version 
number is 0x0100. 


mtSize 
Specifies the size, in words, of the file. 


mtNoObjects | 
Specifies the maximum number of objects that exist in the metafile at the same 
time. : 7 


mtMaxRecord 
Specifies the size, in words, of the largest record i in the metafile. 


mtNoParameters 
Reserved. 


SeeAlso METARECORD 
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METARECORD - a) 


typedef struct tagMETARECORD { /* mr */ 
DWORD rdSize; 
UINT rdFunction; 
UINT rdParm[1]; 

} METARECORD; 


The METARECORD structure contains a metafile record. 


Members rdSize 
Specifies the size, in words, of the record. 


rdFunction 
Specifies the function number. 


rdParm 
Specifies an array of words containing the function parameters, in the reverse 
order in which they are passed to the function. 


See Also METAHEADER 


MINMAXINFO Ex 


typedef struct tagMINMAXINFO { /* mmi */ 
POINT ptReserved; | : 
POINT ptMaxSize; 
POINT ptMaxPosition; 
POINT ptMinTrackSize; 
POINT ptMaxTrackSize; 

} MINMAXINFO; : 


The MINMAXINEFO structure contains information about a window’s maximized 
size and position and its minimum and maximum tracking size. 


Members ptReserved 
Reserved for internal use. 


ptMaxSize 
Specifies the maximized width (point.x) and the maximized height (pointy) of 
the window. 
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ptMaxPosition 
Specifies the position of the left side of the maximized window (point.x) and — 
the position of the top of the maximized window (point.y). 


ptMinTrackSize 
_ Specifies the minimum tracking width (point.x) and the minimum tracking 
height (point.y) of the window. 


ptMaxTrackSize | 
Specifies the maximum tracking width (point.x) and the maximum tracking 
height (point.y) of the window. 


See Also POINT, WM_GETMINMAXINFO 


MODULEENTRY ~— Bw 


#Hinclude <toolhelp.h> 


typedef struct tagMODULEENTRY { /* me */ 
DWORD dwSize; 
char szModuleLMAX_MODULE_ NAME + 1]; 
HMODULE hModule; | 
WORD wcUsage; 
char szExePath[MAX_PATH + 1]; 
WORD wNext; 

} MODULEENTRY; 


The MODULEENTRY structure contains information about one module in the 
module list. 


| Members . dwSize 
| | Specifies the size of the MODULEENTRY structure, in bytes. 


szModule 
Specifies the null- terminated string that contains the module name. — 


hModule | 
Identifies the module handle. 


wcUsage 
Specifies the reference count of the module. This is the same number returned 
by the GetModuleUsage function. 
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szExePath 
Specifies the null-terminated string that contains the fully-qualified executable 
path for the module. 


wNext 
Specifies the next module in the module list. This member is reserved for inter- 
nal use by Windows. | 


See Also ModuleFindHandle, ModuleFindName, ModuleFirst, ModuleNext 


MONCBSTRUCT Bt 


dHinclude <ddeml.h> 


typedef struct tagMONCBSTRUCT { /* mcbst */ 
UINT cb; 
WORD wReserved; 
DWORD dwlime; 
HANDLE —hTask; 
DWORD dwRet; 


UINT wlype; 
UINT wFmt ; 
HCONV hConv; 
HSZ hszl; 
-HSZ ~ hsz2; 


HDDEDATA hData; 

DWORD dwDatal; 

DWORD dwData2; 
} MONCBSTRUCT;- 


The MONCBSTRUCT structure contains information about the current dynamic 
data exchange (DDE) transaction. A DDE debugging application can use this struc- 
ture when monitoring transactions that the system passes to the DDE callback 
functions of other applications. 
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Members cb | 
Specifies the nee in bytes, of the structure. 


wReserved 
Reserved. 


dwTime © | 
Specifies the Windows time at which the transaction occurred. Windows time 
is the number of milliseconds that have elapsed since the system was Started. 


hTask 
Identifies the task (application instance) containing the DDE callback function 
that received the transaction. 


dwRet 
Specifies the value returned by the DDE callback function that processed the 
transaction. 


wlype 


Specifies the transaction type. 


wF mt 
Specifies the format of the data (if any) exchanged during the transaction. 


hConv 
Identifies the < conversation in which the transaction took place. 


hsz1 
Identifies a string. 


hsz2 
Identifies a string. 
hData 
Identifies the data (if any) exchanged during the transaction. 


dwDatal 
Specifies additional data. 


dwData2_ | 
Specifies additional data. 


See Also - MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, | 
, MONMSGSTRUCT 
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MONCONVSTRUCT ~ 


Members 


See Also 


d4tinclude <ddeml.h> 


typedef struct tagMONCONVSTRUCT { /* mcvst */ 
UINT cb; 
BOOL fConnect; 
DWORD dwlime; 
HANDLE hTask; 
HSZ hszSve; 
HSZ hszTopic; 
HCONV hConvClient; 
HCONV hConvServer; 
} MONCONVSTRUCT; 


The MONCONVSTRUCT structure contains information about a conversation. 
A dynamic data exchange (DDE) monitoring application can use this structure to 
obtain information about an advise loop that has been established or terminated. 


cb 
Specifies the length, in bytes, of the structure. 


fConnect 7 
Indicates whether the conversation is currently established. A value of TRUE 
indicates the conversation is established; FALSE indicates it is not. 


dwTime 
Specifies the Windows time at which the conversation was established or termi- 
nated. Windows time is the number of milliseconds that have elapsed since the | 
system was started. 


hTask | 
Identifies a task (application instance) that is a partner in the conversation. 


hszSvc . 

Identifies the service name on which the conversation is established. 
hszTopic 

Identifies the topic name on which the conversation is established. 


hConvClient | 
Identifies the client conversation. 


hConvServer 
Identifies the server conversation. 


MONCBSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, 
MONLINKSTRUCT, MONMSGSTRUCT 
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/MONERRSTRUCT iS os ee 


acide <ddem] .h> 


typedef struct tagMONERRSTRUCT { /* mest */ 
UINT cb; 
UINT wLastError; 
DWORD dwTime; 
HANDLE htTask; 
} MONERRSTRUCT; 


The MONERRSTRUCT structure contains information about the current dy- 
namic data exchange (DDE) error. A DDE monitoring application can use this 
structure to monitor errors returned by DDE Management Library functions. 


Members _ cb | . 
Specifies the length, in bytes, of the structure. 


wLastError 
Specifies the current error. 


dwTime ) | 
Specifies the Windows time at which the error occurred. Windows time is the 
number of milliseconds that have elapsed since the system was started.: 


hTask 
Identifies the task application i instance) that called the DDE function that 
caused the error. 


SeeAlso MONCBSTRUCT, MONCONVSTRUCT, MONHSZSTRUCT, 
MONLINKSTRUCT, MONMSGSTRUCT 
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MONHSZSTRUCT 


Members 


dFinclude <ddeml.h> 


typedef struct tagMONHSZSTRUCT { /* mhst */ 
UINT cb; 
BOOL fsAction; 
DWORD dwTime; 
HSZ hsz; 
HANDLE hTask; 
WORD wReserved; 
char str{1]; 
} MONHSZSTRUCT; 


The MONHSZSTRUCT structure contains information about a dynamic data 
exchange (DDE) string handle. A DDE monitoring application can use this struc- 
ture when monitoring the activity of the string-manager component of the DDE 
Management Library (DDEML). 


cb 
Specifies the length, in bytes, of the structure. 
fsAction 


Specifies the action being performed on the string handle identified by the hsz 
member. 


Value Meaning 


MH_CLEANUP An application is freeing its DDE resources, causing the sys- 
: tem to delete string handles that the application had created. 
(The application called the DdeUninitialize function.) 


MH_CREATE An application is creating a string handle. (The application 
called the DdeCreateStringHandle function.) 

MH_DELETE An application is deleting a string handle. (The application 
called the DdeF reeStringHandle function.) 

MH_KEEP An application is increasing the use count of a string handle. 


(The application called the DdeKeepStringHandle function.) 


dwTime | 
Specifies the Windows time at which the action specified by the fsAction mem- 
ber takes place. Windows time is the number of milliseconds that have elapsed 
since the system was booted. 


hsz | 
Identifies the string. 


hTask | 
Identifies the task (application instance) performing the action on the string 
handle. | | 


See Also 
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wReserved 
Reserved. 


str 
Points to the string identified by the hsz member. 


MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, 
MONLINKSTRUCT, MONMSGSTRUCT 
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Members 


#include <ddeml.h> 


typedef struct tagMONLINKSTRUCT { /*-.mlst */ 
UINT cb; 
DWORD dwtlime; 
HANDLE hTask; 
BOOL fEstablished; 
~BOOL fNoData; 


~HSZ hszSvc; 

~HSZ hszTopic; 
HSZ hszItem; 
UINT wFmt ; 


BOOL fServer; 

HCONV hConvServer; 

HCONV hConvClient; 
j MONLINKSTRUCT ; 


The MONLINKSTRUCT structure contains information about a Rites data 
exchange (DDE) advise loop. A DDE monitoring application can use this structure 
to obtain information about an advise loop that has started or ended. 


cb 
Specifies the length, in ph of the structure. 


dwTime : 
Specifies the Windows time at which the advise loop was started or ended. Win- 
dows time is the number of milliseconds that have elapsed since the system was 
started. 


hTask 
Identifies a task (application instance) that is a partner in the advise loop. 


{Established 
Indicates whether an advise loop was successfully established. A value of 
TRUE indicates an advise loop was established; FALSE indicates an advise 
loop was not established. 
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See Also 
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fNoData 
Indicates whether the XTYPF NODATA flag was set oo the advise loop. A 
value of TRUE indicates the rae is Set; FALSE indicates the flag was not set. 


~ hszSve 


Identifies the service name of the server in the advise loop. 


hszTopic 
Identifies the topic name on which the advise loop is established. 


hszItem 
Identifies the item name that is the subject of the advise loop. 


wk mt 
Specifies the format of the data exchanged (if any) during the advise loop. 


fServer 
Indicates whether the link notification came from the server. If the notification 
came from the server, this value is TRUE. Otherwise, it is FALSE. 


hConvServer 
Identifies the server conversation. 


hConvClient 
Identifies the client conversation. 


MONCBSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, 
MONMSGSTRUCT 


#tinclude <ddem] .h> 


typedef struct tagMONMSGSTRUCT { /* mmst */ 
UINT cb; 
HWND hwndTo; 
DWORD dwlime; 
HANDLE hTask; 
UINT ~~ wMsg; 
WPARAM wParam; 
LPARAM 1Param; | 


} MONMSGSTRUCT; 


The MONMSGSTRUCT structure contains information about a dynamic data ex- 


_ change (DDE) message. A DDE monitoring application can use this structure to 


obtain information about a DDE message that was sent or posted. 
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Members cb | 
Specifies the length, in bytes, of the structure. 


hwndTo 
Identifies the window that receives the DDE message. 


dwTime | 
Specifies the Windows time at which the message was sent or posted. Windows 
time is the number of milliseconds that have elapsed since the system was 
started. 


hTask 
Identifies the task (application instance) contannne the window that receives 
the DDE message. 


wMsg 
Specifies the identifier of the DDE message. 


wParam 
Specifies the wParam parameter of the DDE message. 


[Param 
Specifies the /Param parameter of the DDE message. 


See Also MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, 
MONHSZSTRUCT, MONLINKSTRUCT 


MOUSEHOOKSTRUCT — es) 


typedef struct tagMOUSEHOOKSTRUCT { /* ms */ 
POINT pt; 
HWND hwnd; 
UINT  wHitTestCode; 
DWORD dwExtralInfo; 
-} MOUSEHOOKSTRUCT; 


The MOUSEHOOKSTRUCT structure contains information about a mouse 
event. 


Members pt | 
Specifies a POINT structure that contains the x- and y-coordinates of the 
mouse cursor, in screen coordinates. 


hwnd 


_ Identifies the window that will receive the mouse eee that corresponds to 
the mouse event. 


| 
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wHitTestCode 
Specifies the hit-test code. 


dwExtraInfo 
Specifies extra information associated with the mouse event. An application 
can set this information by calling the hardware_event function and retrieve 
this information by calling the GetMessageExtraInfo function. 


See Also — GetMessageExtralnfo, SetWindowsHook 


MSG a a 


typedef struct tagMSG { /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 


DWORD time; 
POINT pt; 
} MSG; 


The MSG structure contains information from the Windows application queue. 


Members hwnd 
Identifies the window that receives the message. 


message 
Specifies the message number. 


wParam 
Specifies additional information about the message. The exact meaning de- 
pends on the message value. 


IParam 
Specifies additional information about the message. The exact meaning de- 
pends on the message value. 

time 
Specifies the time at which the message was posted. 


pt | | | 
Specifies the position of the cursor, in screen coordinates, when the message 
was posted. : 


See Also EVENTMSG, GetMessage 
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MULTIKEYHELP 


typedef struct tagMULTIKEYHELP { /* mkh */ 
UINT mkSize; | 
BYTE mkKeylist; 
BYTE szKeyphrase[1]; 

} MULTIKEYHELP; 


The MULTIKEYHELP structure specifies a keyword table and an associated 
keyword to be used by the Windows Help application. 


Members mkSize 
Specifies the length, in bytes, of the MULTIKEYHELP structure. 


mkKeylist 
Contains a single character that identifies the eer table to be searched. 


szKeyphrase 
Contains a null-terminated text string that specifies the essai to be located in 


the keyword table. 


See Also WinHelp 


NCCALCSIZE PARAMS i (asttiti—s a 


typedef struct tagNCCALCSIZE_PARAMS { 
RECT. rorcl3]; | 
WINDOWPOS FAR* lppos; 

} NCCALCSIZE_ PARAMS; 


The NCCALCSIZE_ PARAMS structure contains information that an applica- 
tion can use while processing the WM_NCCALCSIZE message to calculate the 
size, position, and valid contents of the client area of a window. 


Members | rere 

-. Specifies an array of rectangles. The first contains the new coordinates of a win-. 
dow that has been moved or resized. The second contains the coordinates of the 
window before it was moved or resized. The third contains the coordinates of 
the client area of a window before it was moved or resized. If the window is a 
child window, the coordinates are relative to the client area of the parent win- 
dow. If the window is a top-level window, the coordinates are relative to the 
screen. 
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Ippos 3 
Points to a WINDOWPOS structure that contains the size and position values 
specified in the operation that caused the window to be moved or resized. The - 
WINDOWPOS structure has the following form: 


typedef struct tagWINDOWPOS { /* wp */ 


HWND hwnd; | 

HWND hwndInsertAfter; 
int x3 

int sy; 

int CX; 

int Cy; 


UINT flags; 
} WINDOWPOS; 


See Also MoveWindow, SetWindowPos, RECT, WINDOWPOS, WM_NCCALCSIZE 


NEWCPLINFO a Ex 


#Finclude <cpl.h> 


typedef struct tagNEWCPLINFO { /* ncpli */ 
DWORD dwSize; 
DWORD dwFlags; 
DWORD dwHelpContext; 
LONG 1Data; 
HICON hIcon; 
char szName[32]; 
char szInfo[64]; 
char szHelpFile[128]; 
} NEWCPLINFO; 


The NEWCPLINFO structure contains resource information and a user-defined | 
value for a Control Panel application. | 


Members 
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dwSize | 
Specifies the length of the structure, in bytes. 


dwFlags 
Specifies Control Panel flags. 


dwHelpContext 
Specifies the context number for the topic in the help project (.HPJ) file that dis- 
plays when the user selects help for the application. For more information on 
help, see Microsoft Windows Programming Tools. 


IData | 
Specifies data defined by the application. 


hicon 
Identifies an icon resource for the application icon. This icon is displayed in the 
Control Panel window. 


szName | 
Specifies a null-terminated string that contains the application name. The name 
is the short string displayed below the application icon in the Control Panel win- 
_ dow. The name is also displayed in the Settings menu of Control Panel. 


szInfo | 7 
Specifies a null- terminated string containing the application description. The de- 
‘scription displayed at the bottom of the Control Panel window when the applica- 
tion icon is selected. 


szHelpFile 
Specifies a null-terminated string that contains the path of the help file, if any, 
_ for the application. 
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NEWTEXTMETRIC 


Members 


typedef struct tagNEWTEXTMETRIC { /* ntm */ 
int tmHei ght; | 
int tmAscent; 
int tmDescent; 
int |. tmInternalLeading; 
int’  tmExternalLeading; 

int  tmAveCharWidth; | 

int tmMaxCharWidth; 
int p ES VOTES: 
BYTE tmItalic; 
BYTE tmUnderlined; 
BYTE tmStruckOut.; 
BYTE tmFirstChar; 
BYTE tmLastChar; 
BYTE tmDefaultChar; 
BYTE tmBreakChar; 
BYTE tmPitchAndFamily; 
BYTE tmCharSet; 
int tmOverhang; 
int tmDigitizedAspectx; 
int tmDigitizedAspectyY ; 
DWORD ntmFlags; 
UINT ntmSizeEM; 
UINT ntmCellHeight; 
UINT ntmAvgWidth; 


} NEWTEXTMETRIC; 


The NEWTEXTMETRIC structure contains basic information about a physical 
font. The last four members of the NEWTEXTMETRIC structure are not in- 
cluded in the TEXTMETRIC structure; in all other respects, the structures are 
identical. The additional members are used for information about TrueType fonts. 


tmHeight | | 
Specifies the height of character cells. (The height is the sum of the tmAscent 
and tmDescent members.) 


tmAscent | | : 
Specifies the ascent of character cells. (The ascent is the space between the base 
line and the top of the character cell.) 


tmDescent 


Specifies the descent of character cells. (The descent is the space between the 
bottom of the character cell and the base line.) | 


tmInternalLeading | 
Specifies the difference between the point size of a font and the physical 
size of the font. For TrueType fonts, this value is equal to tmHeight minus 
— (s * ntmSizeEM), where s is the scaling factor for the TrueType font. For 
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bitmap fonts, this value is used to determine the point size of a font; when an ap- 
plication specifies a negative value in the IfHeight member of the LOGFONT | 
structure, the application is requesting a font whose height equals tmHeight 
minus tmInternalLeading. 


tmExternalLeading 
Specifies the amount of extra leading (space) that the application adds between 
rows. Since this area is outside the character cell, it contains no marks and will 
not be altered by text output calls in either opaque or transparent mode. The 
font designer sometimes sets this member to zero. 


tmAveChar Width 
Specifies the average width of characters in the font. For ANS]_CHARSET 
fonts, this is a weighted average of the characters “a” through “z” and the space 
character. For other character sets, this value is an unweighted average of all 
characters in the font. 


tmMaxChar Width 


Specifies the “B” spacing of the widest character in the font. For more informa- 
tion about “B” spacing, see the description of the ABC structure. 


tmWeight 
| Specifies the weight of the font. This member can be one of the following 
values: 


Constant | Value 
FW_DONTCARE 0 
FW_THIN 100 


FW_EXTRALIGHT 200 
FW_ULTRALIGHT 200 


FW_LIGHT 300 
FW_NORMAL 400 
FW_REGULAR 400 
FW_MEDIUM 500 
FW._SEMIBOLD __ 600 

_ FW_DEMIBOLD 600 
FW_BOLD 700 


FW_EXTRABOLD 800 
FW_ULTRABOLD 800 


FW_BLACK | 900 
FW_HEAVY 900 © 
tmItalic 


Specifies an italic font if it is nonzero. 


 tmUnderlined ; 
Specifies an underlined font if it is nonzero. 
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tmStruckOut 
Specifies a “struckout” font if it is nonzero. 


tmFirstChar | 
Specifies the value of the first character defined in the font. 


| tmLastChar 


Specifies the value of the last character defined in the font. 


tmDefaultChar 
Specifies the value of the character that will be substituted for characters not in 
the font. 


tmBreakChar 
Specifies the value of the character that will be used to define word breaks for 
text justification. 


tmPitchAndFamily 
Specifies the pitch and family of the selected font. The four low-order bits iden- — 
tify the type of font, as follows: 


Value ss Meaning 

TMPF_PITCH Designates a fixed-pitch font. 
TMPF_VECTOR __s Designates a vector or TrueType font. 
TMPF_TRUETYPE Designates a TrueType font. 
TMPF_DEVICE Designates a device font. 


Some fonts are identified by several of these bits—for example, the bits 
TMPF_PITCH, TMPF_VECTOR, and TMPF_TRUETYPE would be set for 
the monospace TrueType font, Courier New. The TMPF_DEVICE bit could be 
set for a TrueType font as well, because this bit is set for both downloaded and 
device-resident fonts. 


When the TMPF_TRUETYPE bit is set, the font is usable on all output devices. 
For example, if a TrueType font existed on a printer but could not be used on 
the display, the TMPF_TRUETYPE bit would not be set for that font. 


The four high-order bits specify the font family. The tmPitchAndFamily mem- 
ber can be combined with the hexadecimal value OxFO by using the bitwise _ 
AND operator and can then be compared with the font family names for an 
identical match. The following font families are defined: 


Value | Meaning 
FF_DECORATIVE Novelty fonts. Old English is an example. 
FF_DONTCARE Don’t care or don’t know. | 
FF_MODERN Fonts with constant stroke width, with or without serifs. 
we Pica, Elite, and Courier New are examples. 
_ FF_ROMAN Fonts with variable stroke width and with serifs. Times 


New Roman and New Century Schoolbook are examples. 
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~ Value Meaning 


FF_SCRIPT Fonts designed to look like handwriting. Script and Cursive 
| | are examples. 
FF_SWISS Fonts with variable stroke width and without serifs. > 
Sans Serif is an example. 
tmCharSet | | 
Specifies the character set of the font. The following values are defined: 
Constant Value | 
ANSI_CHARSET 0 


_ DEFAULT_CHARSET 1 

SYMBOL_CHARSET 2 
-SHIFTJIS_CHARSET 128 
OEM_CHARSET 255 


tmOverhang 
Specifies the extra width that is added to some synthesized fonts. When synthe-. 
sizing some attributes, such as bold or italic, graphics-device interface (GDI) or 
a device adds width to a string on both a per-character and per-string basis. For 
example, GDI makes a string bold by expanding the intracharacter spacing and 
overstriking by an offset value and italicizes a font by skewing the string. In 
either case, the string is wider after the attribute is synthesized. For bold strings, 
the overhang is the distance by which the overstrike is offset. For italic strings, 
the overhang is the amount the top of the font is skewed past the bottom of the 
font. 


The tmOverhang member is zero for many italic and bold TrueType fonts be- 
- cause many TrueType fonts include italic and bold faces that are not synthe- 
sized. For example, the overhang for Courier New Italic is zero. 


An application that uses raster fonts can use the overhang value to determine 
the spacing between words that have different attributes. _ 


tmDigitizedAspectX 
‘Specifies the horizontal aspect of the device for which the font was designed. 


_ tmDigitizedAspectY 
_ Specifies the vertical aspect of the device for which the font was designed. The 
ratio of the tmDigitizedAspectX and tmDigitizedAspectY members is the 
aspect ratio of the device for which the font was designed. 


ntmFlags | 
Specifies some elements of the font style. This member can be one or more of 
the following values: 


-NTM_REGULAR 
NTM_BOLD | 
NTM_ITALIC — 
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The NTM _BOLD and NTM_ITALIC flags could be combined with the OR 
operator to specify a bold italic font. 


ntmSizeEM 
Specifies the size of the em square for the font, in the units for which the Font 
was designed (notional units). 


ntmCellHeight 
Specifies the height of the font, in the units for which the font was designed 
(notional units). This value should be compared against the value of the 
ntmSizeEM member. 


ntmAvge Width 
Specifies the average width of characters inthe font, in the units for which the 
font was designed (notional units). This value should be compared against the 
value of the ntmSizeEM member. 


Comments | The sizes in the NEWTEXTMETRIC structure are typically given in logical 
units; that is, they depend on the current mapping mode of the display context. 


See Also EnumFontFamilies, EnumFonts, GetDeviceCaps, GetTextMetrics 


NFYLOADSEG oa 


#include <toolhelp.h> 


typedef struct tagNFYLOADSEG { /* nfyls */ 
DWORD dwSize; . 
WORD  - wSelector; 
WORD wsegNum; 
WORD wlype; 
WORD wcInstance; 
LPCSTR lpstrModuleName; 
} NFYLOADSEG; 


The NFYLOADSEG structure contains information about the segment being 
loaded when the kernel sends a load-segment notification. | 


Members dwSize 
| Specifies the size of the NFYLOADSEG structure, in i bytes. - 


wselector 
Contains the selector of the segment Delile loaded. 


wSegNum 
Contains the executable-file segment number. 
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wlype 
Indicates the type of information in the segment. Only the low bit of wType is 
used. This type can be one of the following values: 


Value Meaning 

0 The segment contains code. 

1 The segment contains data. 
wclInstance 


Specifies the number of instances that share this segment. This value is valid 
only for data segments. 


Ipstr ModuleName 
Points to a null-terminated string containing the name of the module that owns 


the segment being loaded. 


See Also_ NotifyRegister 


NFYLOGERROR eee 
dFinclude <toolhelp.h> 


typedef struct tagNFYLOGERROR { /* nfyle */ 
DWORD dwSize; 
UINT wErrCode; 
| void FAR* IpInfo; 
} NFYLOGERROR; 


The NFYLOGERROR structure contains information about a walidacon error 
; that caused the kernel to send an NFY_LOGERROR notification. 


Members |  dwSize 
| | Specifies the size of the NFYLOGERROR structure, in bytes: 


wErrCode 
Identifies the error value that caused the noticguian, to be sent. 


- IpInfo 
Points to additional information, dependent on the error value. 


SeeAlso ts NotifyRegister 
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NFYLOGPARAMERROR By 


#Hinclude <toolhelp.h> 


typedef struct tagNFYLOGPARAMERROR { /#* nfylpe */ 


DWORD és dwSize; 
UINT wErrCode; 
FARPROC ITpfnErrorAddr; 


void FAR* FAR* 1]pBadParam; 
} NFYLOGPARAMERROR; 


The NFYLOGPARAMERROR structure contains information 
about a parameter-validation error that caused the kernel to send an 
NFY_LOGPARAMERROR notification. 


Members dwSize : | 
Specifies the size of the NFYLOGPARAMERROR structure, in bytes. 


wErrCode 
Identifies the error value that caused the notification to be sent. 


IpfnErrorAddr 
Points to the address of the function with the invalid parameter. 


IpBadParam 
Points to the name of the invalid parameter. 


See Also NotifyRegister 


NFYRIP a 
#Finclude <toolhelp.h> | 


typedef struct tagNFYRIP { /* nfyr */ 
DWORD dwSize; 
WORD wIP; — 
WORD wCS; 
WORD wSS; 
WORD wBP; 
WORD wExitCode; 
} NEYRIP: 


The NFYRIP si structure contains information about the system when a system de- 
bugging error (RIP) occurs. 


Members 


Comments 


See Also 


NFYSTARTDLL 


Members ' 
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dwSize | 
Specifies the size of the NFYRIP structure, in bytes. 


wIP 
Contains the value in the IP register at the time of the RIP. 


wCs 
Contains the value in the CS register at the time of the RIP. 


wss 
Contains the value in the SS register at the time of the RIP. 


wBP 
Contains the value in the BP register at the time of the RIP. 


wExitCode 
Contains an exit code that describes any the RIP occurred, 


The StackTraceCSIPFirst function uses the CS:IP and SS:BP values er in 
this structure. The first frame in the stack identified by these values points to the _ 
FatalExit function. The next frame points to the routine that called FatalExit, usu- 
ally in USER.EXE, GDI.EXE, or either KRNL286.EXE or KRNL386.EXE. 


FatalExit, NotifyRegister, StackTraceCSIPFirst 


#Finclude <toolhelp.h> 


typedef struct tagNFYSTARTDLL { /* nfysd */ 
DWORD  dwSize; 
HMODULE hModule; 
WORD wCS; 
WORD wIP; 


# NFYSTARTDLL; 


The NFYSTARTDLL structure contains information about the dynamic-link 
library ae loaded when the kernel sends a load-DLL notification. 


dwSize 
Specifies the size of the NFYSTARTDLL structure, in bytes. 


hModule — 
Identifies the ee module being loaded. 
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See Also 


OFSTRUCT 


Members 


Comments 


wCS 


Contains the value in the CS register at load time. This value is used with the 
value of the wIP member to determine the load address of the library. 


wIP 
Contains the value in the IP register at load time. This value is used with the 
wCS value to determine the load address of the library. 


NotifyRegister 


typedef struct tagOFSTRUCT { /* of */ 
BYTE cBytes; 
BYTE fFixedDisk; 
UINT neErrCode; 
BYTE reserved[4]; 
BYTE szPathName[128]; 
} OFSTRUCT; — 


The OFSTRUCT structure contains file information which results from opening 
that file. 


cBytes 
Specifies the length, in bytes, of the OFSTRUCT structure. 

fFixedDisk 
Specifies whether the file is on a fixed disk. The fFixedDisk member is non- 
zero if the file is on a fixed disk. 


nErrCode 
Specifies the MS-DOS error value if the OpenFile function returns —1 (that is, 
OpenFile fails). For a list of possible error values, see the following Comments 
section. 


reserved 
Reserved member. Four bytes reserved for future use. 


szPathName 
Specifies 128 bytes that contain the path of the file. This string consists of char- 
acters from the OEM character set. 


The error values that may be specified in the nErrCode parameter follow: 


Value 


0x0001 
0x0002 
0x0003 
0x0004 
0x0005 
0x0006 
0x0007 
0x0008 
0x0009 
0x000A 
0x000B 
0x000C 
0x000D 
0xO00F 
0x0010 
0x0011 
0x0012 
0x0013 
0x0014 
0x0015 
0x0016 
0x0017 
0x0018 
0x0019 
0x001A 
0x001B 
0x001C 
0x001D 
Ox001E 
0x001F 
0x0020 
0x0021 
0x0022 
0x0023 
0x0024 
0x0032 
0x0033 
0x0034 


OFSTRUCT 


Meaning 


Invalid function — 
File not found 
Path not found 
Too many open files 
Access denied 
Invalid handle 
Arena trashed 

Not enough memory 
Invalid block 

Bad environment 
Bad format 
Invalid access 
Invalid data 
Invalid drive 
Current directory 
Not same device 
No more files 
Write protect error 
Bad unit 

Not ready 

Bad command 
CRC error 

Bad length 

Seek error 

Not MS-DOS disk 
Sector not found 
Out of paper 
Write fault 


~ Read fault 


General failure 

Sharing violation 

Lock violation 

Wrong disk 

File control block unavailable 
Sharing buffer exceeded 

Not supported 

Remote not listed 

Duplicate name 
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See Also 
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Value 


0x0035 
0x0036 
0x0037 
0x0038 
0x0039 
0x003A 
0x003B 
0x003C 
0x003D 
0x003E 
0x003F 
0x0040 
0x0041 
0x0042 
0x0043 
0x0044 
0x0045 
0x0046 
0x0047 
0x0048 
0x0050 
0x0051 
0x0052 
0x0053 
0x0054 
0x0055 
0x0056 
0x0057 
0x0058 


OpenFile 


Meaning 


Bad netpath 

Network busy 

Device does not exist - 
Too many commands 
Adaptor hardware error 
Bad network response 
Unexpected network error 
Bad remote adaptor 

Print queue full 

No spool space 

Print canceled 

Netname deleted 
Network access denied 
Bad device type 

Bad network name 

Too many names 

Too many sessions 
Sharing paused 

Request not accepted 
Redirection paused 

File exists 

Duplicate file control block 
Cannot make 
Interrupt 24 failure 
Out of structures 
Already assigned 
Invalid password 
Invalid parameter 
Net write fault 


OLECLIENT 


Members 


Comments 
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[3.1 | 


dkinclude <ole.h> 


typedef struct _OLECLIENT { /* oc */ 
LPOLECLIENTVTBL lIpvtb1; 


/* any client-supplied state information */ 


} OLECLIENT; 


The OLECLIENT structure points to an OLECLIENTVTBL structure and can 
store state information for use by the client application. 


Ipvtbl 
Points to a table of function pointers for the client. 


Servers and object handlers should not attempt to use any state information sup- 
plied in the OLECLIENT structure. The use and meaning of this information is 
entirely dependent on the client application. Because a pointer to this structure is 
supplied as a parameter to the client’s callback function, this is the preferred 
method for the client application to store private object-state information. 


OLECLIENTVTBL Ba 


Comments 


dEinclude <ole.h> 


typedef struct _OLECLIENTVTBL { /* ocv */ 

int (CALLBACK* CallBack)(LPOLECLIENT, OLE_NOTIFICATION, 
LPOLEOBJECT); 
} OLECLIENTVTBL; 


The OLECLIENTVTBL structure contains a pointer to a callback function for 
the client application. 


_ The address passed as the CallBack member must be created by using the Make- 
ProcInstance function. 
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Suacian | ClientCallback 


INT ClientCallback (/pclient, notification, lpobject) 
LPOLECLIENT Ipclient; 
OLE_ NOTIFICATION notification; 


LPOLEOBJECT Ipobject; 
The ClientCallback function must use the Pascal calling convention and must fie 
declared FAR. 

Parameters — [pclient 


Points to the client structure associated with the object. The library retrieves 
this pointer from its object structure when a notification occurs, uses it to locate 
the callback function, and passes the pointer to the client structure for the client 
application’s use. 


notification 
Specifies the reason for the notification. This parameter can be one of the fol- 
lowing values: : 


Value | Meaning 


OLE_CHANGED The linked object has changed. (This notification is 
not sent for embedded objects.) A typical action to 
take with this notification is either to redraw or to 
save the object. 


OLE_CLOSED| The object has been closed in its server. When the 
client receives this notification, it should not call any 
function that causes an asynchronous operation until 
it regains control of program execution. 


OLE_QUERY_ PAINT A lengthy drawing operation is occurring. This notifi- 
cation allows the drawing to be interrupted. 


OLE_QUERY_ RETRY The server has responded to a request by indicating 
that it is busy. This notification requests the client to 
determine whether the library should continue to 
make the request. If the callback function returns 
FALSE, the transaction with the server is discon- 
tinued. 


OLE_ RELEASE The object has been released because an asynchro- 
nous operation has finished. The client should not quit 
until all objects have been released. The client applica- 
tion can call the OleQueryReleaseError function to 
determine whether the operation succeeded. It can 
also call the OleQueryReleaseMethod function, if 
necessary, to verify that that operation has ended 


Return Value 


Comments 


See Also 
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Value Meaning 


OLE_RENAMED The linked object has been renamed in its server. This 
notification is for information only, because the 
library automatically updates its link information. 

OLE_SAVED The linked object has been saved in its server. The 
client receives this notification when the server calls 
the OleSavedServerDoc function in response to the 

user choosing the Update command in the server’s 
File menu. 


When the client receives the OLE_ CLOSED notification, it typically stores 
the condition and returns to the client library, taking action only when the client 
library returns control of program execution to the client application. If the 
client application must take action before regaining control, it should not call 
any functions that could result in an asynchronous operation. 


lpobject | 
Points to the object that caused the notification to be sent. Applications that use 
the same client structure for more than one object use the /pobject parameter to 
distinguish between notifications. 


When the notification parameter specifies either OLE_LQUERY_PAINT or 
OLE_QUERY_RETRY, the client should return TRUE if the library should 
continue, or FALSE to terminate the painting operation or discontinue the 
server transaction. When the notification parameter does not specify either 
OLE_QUERY_PAINT or OLE_QUERY_RETRY, the return value is ignored. 


The client application should act on these notifications at the next appropriate 
time; for example, as part of the main event loop or when closing the object. The 
updating of an object can be deferred until the user requests the update, if the 
client provides that functionality. The client may call the library from a notifica- 
tion callback function (the library is reentrant). The client should not attempt an 
asynchronous operation while certain other operations are in progress (for ex- 
ample, opening or deleting an object). The client also should not enter a message- 
dispatch loop inside the callback function. When the client application calls a 
function that would cause an asynchronous operation, the client library returns 
OLE_WAIT_FOR_RELEASE when the function is called, notifies the application 
when the operation completes by using OLE_RELEASE, and returns OLE_BUSY 
if the client attempts to invoke a conflicting operation while the previous one is in 
progress. The client can determine if an asynchronous operation is in progress by 
calling OleQueryReleaseStatus, which returns OLE_BUSY if the operation has 
not yet completed. 


OleQueryReleaseStatus 
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OLEOBJECT 


#Finclude <ole.h> 


typedef struct _OLEOBJECT { /* 00 */ 
LPOLEOBJECTVTBL lpvtb1; 


/* any server-supplied state information */ 


} OLEOBJECT; 


The OLEOBJECT structure points to a table of function pointers for an object. 
This structure is initialized and maintained by servers for the server library. 


Members Ipvtbl 


Points to a table of function pointers for the object. 


OLEOBJECTVTBL 


#tinclude <ole.h> 


typedef struct _OLEOBJECTVTBL { /* oov */ 


void FAR* (CALLBACK* 
OLESTATUS (CALLBACK* 
OLESTATUS (CALLBACK* 
OLESTATUS (CALLBACK* 
OLESTATUS (CALLBACK# 
HANDLE FAR*); 
OLESTATUS (CALLBACK* 
OLESTATUS (CALLBACK* 
OLESTATUS (CALLBACK* 


QueryProtocol )(LPOLEOBJECT, OLE_LPCSTR); 
Release) (LPOLEOBJECT) ; 

Show) (LPOLEOBJECT, BOOL); 
DoVerb)(LPOLEOBJECT, UINT, BOOL, BOOL); 
GetData)(LPOLEOBJECT, OLECLIPFORMAT, 


SetData)(LPOLEOBJECT, OLECLIPFORMAT, HANDLE); 
SetTargetDevice)(LPOLEOBJECT, HGLOBAL); 
SetBounds)(LPOLEOBJECT, OLE_CONST RECT FAR*); 


OLECLIPFORMAT (CALLBACK* EnumFormats)(LPOLEOBJECT, OLECLIPFORMAT); 


OLESTATUS (CALLBACK* 


SetColorScheme) (LPOLEOBJECT, 


OLE_CONST LOGPALETTE FAR#); 


/* 


* Server applications implement only the functions listed above. | 
* Object handlers can use any of the functions in this structure 


* to modify default 
* / . 


server behavior. 
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OLESTATUS (CALLBACK* Delete) (LPOLEOBJECT); 

OLESTATUS (CALLBACK* SetHostNames)(LPOLEOBJECT, OLE_LPCSTR, 
OLE_LPCSTR); 

OLESTATUS (CALLBACK* SaveToStream)(LPOLEOBJECT, LPOLESTREAM)  ; 

OLESTATUS (CALLBACK* Clone)(LPOLEOBJECT, LPOLECLIENT, LHCLIENTDOC, 
OLE_LPCSTR, LPOLEOBJECT FAR*); | | 

OLESTATUS (CALLBACK* CopyFromLink)(LPOLEOBJECT, LPOLECLIENT, 
LHCLIENTDOC, OLE_LPCSTR, LPOLEOBJECT FAR*); © 

OLESTATUS (CALLBACK* Equal )(LPOLEOBJECT, LPOLEQBJECT); 

OLESTATUS (CALLBACK* CopyToClipboard)(LPOLEOBJECT) ; 

OLESTATUS (CALLBACK* Draw)(LPOLEOBJECT, HDC, OLE_CONST RECT FAR#, 
OLE_CONST RECT FAR*, HDC); 

OLESTATUS (CALLBACK* Activate)(LPOLEOBJECT, UINT, BOOL, BOOL, HWND, 
OLE_CONST RECT FAR*); 

OLESTATUS (CALLBACK* Execute)(LPOLEOQBJECT, HGLOBAL, UINT); 

OLESTATUS (CALLBACK* Close) (LPOLEOBJECT) ; 

OLESTATUS (CALLBACK* Update) (LPOLEOBJECT) ; 

OLESTATUS (CALLBACK* Reconnect) (LPOLEOBJECT) ; 

OLESTATUS (CALLBACK* ObjectConvert)(LPOLEOBJECT, OLE_LPCSTR, 
LPOLECLIENT, LHCLIENTDOC, OLE_LPCSTR, LPOLEOBJECT FAR*); 

OLESTATUS (CALLBACK* GetLinkUpdateOptions)(LPOLEOBJECT, 
OLEOPT_UPDATE FAR*); 

OLESTATUS (CALLBACK* SetLinkUpdateOptions )(LPOLEOBJECT, 
OLEOPT_UPDATE) ; | 

OLESTATUS (CALLBACK* Rename)(LPOLEOBJECT, OLE_LPCSTR); 

OLESTATUS (CALLBACK* QueryName)(LPOLEOBJECT, LPSTR, UINT FAR*); 

OLESTATUS (CALLBACK* QueryType)(LPOLEOBJECT, LONG FAR*); 

OLESTATUS (CALLBACK* QueryBounds)(LPOLEOBJECT, RECT FAR*); 

OLESTATUS (CALLBACK* QuerySize)(LPOLEOBJECT, DWORD FAR*); 

OLESTATUS (CALLBACK* QueryOpen) (LPOLEOBJECT) ; 

OLESTATUS (CALLBACK* QueryOutOfDate)(LPOLEOBJECT); 

OLESTATUS (CALLBACK* QueryReleaseStatus) (LPOLEOBJECT); 

OLESTATUS (CALLBACK* QueryReleaseError)(LPOLEOQBJECT ); 

OLE. RELEASE_METHOD (CALLBACK* QueryReleaseMethod)(LPOLEOBJECT); 

OLESTATUS (CALLBACK* RequestData)(LPOLEOBJECT, OLECLIPFORMAT); 

OLESTATUS (CALLBACK* ObjectLong)(LPOLEOBJECT, UINT, LONG FAR*#); 

} OLEOBJECTVTBL; 


The OLEOBJECTVTBL structure points to functions that manipulate an object. 
A server application creates this structure and an OLEOBJ ECT structure to give 
the server library access to an object. 


Server applications do not need to implement functions beyond the SetColor- 
Scheme function. Object handlers can provide specialized treatment for some or 
all of the functions in the OLEOBJECTVTBL structure. 


The following list of structure members does not document all the functions 
pointed to by the OLEOBJECTVTBL structure. For information about the func- 
tions not documented here, see the documentation for the corresponding function 
for object linking and embedding (OLE). For example, for more information about 
the QueryProtocol member, see the OleQueryProtocol function. 
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Comments 


Function 


The following functions in OLEOBJECTVTBL should return OLE _BUSY when 
appropriate: 


Activate SetBounds 

Close SetColorScheme 
CopyFromLink SetData | 

Delete SetHostNames 

DoVerb SetLinkUpdateOptions 
Execute SetTargetDevice 
ObjectConvert Show 

Reconnect — Update 

RequestData 

Release 


OLESTATUS (FAR PASCAL *Release)(/pObject) 
EROLBORIECT lpObject; 


Parameters 


Return Value 


Comments 


Function 


The Release function causes the server to free the resources associated with the 
specified OLEOBJECT structure. 


[pObject 
Points to the OLEOBJECT structure to be released. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


The server application should not destroy data when the library calls the Release 
function. The library calls the Release function when no clients are connected to 
the object. 


Show 


OLESTATUS (FAR PASCAL *Show)(IpObject, flakeFocus) 
LPOLEOBJECT /pObDject; 


BOOL flakeF OCUS} 


- Parameters 


The Show function causes the server to show an object, displaying its window and 
scrolling (if necessary) to make the object visible. 


| IpObject 


Points to the OLEOBJECT Srmucuire to show. 


flakeFocus 


Specifies whether the server window gets the focus. If the server window is to 


get the focus, this value is TRUE. Otherwise, this value is FALSE. 


Return Value 


Comments 


Function 
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The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


The library calls the Show function when the server application should show the 


document to the user for editing or to request the server to scroll the document to” 
bring the ae into view. 


DoVerb 


OLESTATUS (FAR PASCAL *DoVerb)(/pObject, iVerb, fShow, flakeFocus); 
LPOLEOBJECT [pObject; 


UINT iVerb; 
BOOL fShow; 
BOOL flakeFocus; 


Parameters 


Return Value | 


‘Comments 


The DoVerb function specifies what kind of action the server should take when a 
user activates an object. 


lpObject , 
Points to the object to activate. 


iVerb | 
Specifies the action to take. The oe of this parameter is determined by the 
server oe 
fShow 
Specifies whether to show the server window. This value j 1S TRUE to show the 
window; otherwise, it is FALSE. | 
flakeFocus — 
Specifies whether the server window gets the focus. If the server window is to_ 
get the focus, this value is TRUE. Otherwise, it is FALSE. This pe 1S rel- 
evant only if the fShow parameter is TRUE. | 


The return value is eee OK if the function i is successful. Otherwise, it is an error 
value. 


All servers must support the editing of objects. If a server does not support any 
verbs except Edit, it should edit the object no matter what value is specified by the 
iVerb parameter. 
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Function 


GetData 


OLESTATUS (FAR PASCAL *GetData)(/pObject, cfF Cun Iphdata) 
LPOLEOBJECT [pObject; 

OLECLIPFORMAT cfFormat; 

HANDLE FAR* [phdata; 


Parameters 


Return Value 


Function 


The GetData function retrieves data from an object in a specified format. The 
server application should allocate memory, fill it with the data, and return the data 
through the /[phdata parameter. 


lpObject 
Points to the OLEOBJECT structure from which data is requested. 


cfFormat 
Specifies the format in which the data is requested. 


lphdata 
Points to the handle of the allocated memory that the server application returns. 
The library frees the memory when it is no longer needed. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_BLANK 
OLE_ERROR_FORMAT 
OLE_ERROR_OBJECT 


SetData 


OLESTATUS (FAR PASCAL *SetData)(IpObject, cfFormat, hdata) 
LPOLEOBJECT IpObDject; 
OLECLIPFORMAT cfFormat; 


HANDLE hdata; 


Parameters 


The SetData function stores data in an object in a specified format. This function 
is called (with the Native data format) when a client opens an embedded object for 
editing. This function is also used if the client calls the OleSetData function with 
some other format. 7 


lpObject | 
Points to the OLEOBJECT structure in which data is stored. 


cfFormat 
Specifies the format of the data. 


_hdata 


Identifies a place i in memory from which the server application should extract 
the data. The server should delete this handle after it uses the data. 


Return Value 


Comments 


Function 
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The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. | 


The server application is responsible for the memory identified by the hdata 
parameter. The server must delete this data even if it returns OLE_BUSY or if an 
error occurs. 


SetTargetDevice — 


OLESTATUS (FAR PASCAL *SetTargetDevice)(/pObject, hotd) 
LPOLEOBJECT [pObject; 


HGLOBAL hotd; 


Parameters 


Return Value 


The SetTargetDevice function communicates information about the client’s target 
device for the object. The server can use this information to customize output for 
the target device. 


[pObject 
Points to the OLEOBJECT structure for which the target device 1 is specified. 


hotd 
Identifies an OLETARGETDEVICE structure. 


The return value is OLE. OK ft the function is successful. Otherwise, it is an error 
value. 


The server application is responsible for the memory identified by the hotd — 


Comments 
| parameter. The server must delete this data even if it it returns OLE_ BUSY « or if an 
error occurs. 
The library passes NULL for the hotd ae to indicate that the rendering 1 is 
_ necessary for the screen. 
See Also OleSetTargetDevice 
Function — ObjectLong 
OLESTATUS (FAR PASCAL Sp Aaa wFlags, lpData) 
LPOLEOBJECT lpObject; 
UINT wFlags; 
LONG BARS lpData; 


The ObjectLong function allows the sailing application to store data with an ob- 
ject. This function is typically used by object handlers. 
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Parameters 


Return Value 


Function 


[pObject 
Points to the OLEOBJECT structure for which the data is stored. 


wFlags 
Specifies the method used for setting and retrieving data. It can be one or more 
of the following values: 


Value Meaning 

OF_SET Data is written to the location specified by the JpData parame- 
ter, replacing any data already there. 

OF_GET Data is read from the location specified by the /pData parame- 
ter. 


OF_HANDLER Data is written or read by an object handler. This value pre- 
vents data from an object handler from being replaced by other 
applications. 


If the calling application specifies OF_SET and OF_GET, the function returns a 
pointer to the previous data and replaces the data pointed to by the /pData 
parameter with the data specified by the calling application. 


lpData 
Points to data to be written or read. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 3 


SetColorScheme 


OLESTATUS SetColorScheme(/pObject, IpPal) 
LPOLEOBJECT IpObDject; 
OLE_CONST LOGPALETTE FAR* ipPal; 


Parameters 


Return Value 


Comments 


The SetColorScheme function sends the server application the color palette rec- 
ommended by the client application. 


[pObject 
Points to an OLEOBJECT structure for which the client application recom- 
mends a palette. | 


lpPal | | 
Points toa LOGPALETTE structure specifying the recommended palette. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. | 


Server applications are not required to use the palette recommended by the client 
application. 


OLESERVER 


dFinclude <ole.h> — 


Members 
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Before returning from the SetColorScheme function, the server application 
should use the palette pointed to by the /pPal parameter in a call to the Create- 
Palette function to create the handle of the palette: 


hpal = CreatePalette(IpPal); 


The server can then use the palette handle to refer to the palette. 


The first palette entry in the LOGPALETTE structure specifies the foreground © 
color recommended by the client application. The second palette entry specifies 
the background color. The first half of the remaining palette entries are fill colors, 
and the second half are colors for lines and text. 


Client applications typically specify an even number of palette entries. When there 
is an uneven number of entries, the server should interpret the odd entry as a fill 
color; that is, if there are five entries, three should be interpreted as fill colors and 
two as line and text colors. | 


typedef struct - -OLESERVER { | /* os */ 
LPOLESERVERVTBL Ipvtb1; 


‘/* any server-supplied state information */ 


} OLESERVER; » 


The OLESERVER structure points to a table of function pointers for the server. 


This structure is initialized and maintained by servers for the server library. 


Ipvtbl 
Points to a table of fubction pointers for the server. 
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OLESERVERDOC fat 


dFinclude <ole.h> 


typedef struct _OLESERVERDOC { /* osd */ 
LPOLESERVERDOCVTBL Ipvtbl; 


/* any server-supplied document-state information */ 


} OLESERVERDOC; 


The OLESERVERDOC structure points to a table of function pointers for a docu- 
ment. This structure is initialized and maintained by servers for the server library. 


Members  _ Ipvtbl 
Points to a table of function pointers for the document. 


OLESERVERDOCVTBL [3.4 | 


d#Finclude <ole.h> 


typedef struct _OLESERVERDOCVTBL { /* odv */ 
OLESTATUS (CALLBACK* Save) (LPOLESERVERDOC) ; 
OLESTATUS (CALLBACK* Close) (LPOLESERVERDOC) ; 
OLESTATUS (CALLBACK* SetHostNames)(LPOLESERVERDOC, OLE_LPCSTR, 
OLE_LPCSTR); 
OLESTATUS (CALLBACK* SetDocDimensions)(LPOLESERVERDOC, 
OLE_CONST RECT FAR*); 
OLESTATUS (CALLBACK* GetObject)(LPOLESERVERDOC, OLE_LPCSTR, 
LPOLEOBJECT FAR*, LPOLECLIENT); 
OLESTATUS (CALLBACK* Release) (LPOLESERVERDOC) ; 
OLESTATUS (CALLBACK* SetColorScheme) (LPOLESERVERDOC, 
OLE_CONST LOGPALETTE FAR*); 
OLESTATUS (CALLBACK* Execute) (LPOLESERVERDOC, HGLOBAL); 
} OLESERVERDOCVTBL; 


The OLESERVERDOCVTBL structure points to functions that manipulate a 
document. A server application creates this structure and an OLESERVERDOC 
structure to give the server library access to a document. 


Documents opened or created on request from the library should not be shown to 
the user for editing until the library requests that they be shown. 


Every function except Release can return OLE_BUSY. 
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Function | Save 


OLESTATUS Save(/pDoc) 
LPOLESERVERDOC IpDoc; 


The Save function instructs the server to save the document. 


Parameters lpDoc 
Points to an OLESERVERDOC structure coeeidae to the document to 
save. 
Return Value — The return value is OLE_OK if the function is successful. Otherwise, it is an error 
| value. 
Function Close 
OLESTATUS Close(/pDoc) 
LPOLESERVERDOC IpDoc; 


The Close function instructs the server application to unconditionally close the 
document. The library calls this function when the client application initiates the 
closure. 


Parameters lpDoc | 
| Points to an OLESERVERDOC structure corresponding to the document t to | 
close. | : 3 


Return Value The return value is OLE_OK if the cauneton is successful. Otherwise, ‘itis an error 
value. 


Comments | The library always calls the Close fanction before p calling the Release function in 
| the OLESERVERVTBL structure. 


The server application should not prompt the user to save the document or take — 
other actions; messages of this kind are handled by the client application. 


When the library calls the Close function, the server should respond by calling the 
OleRevokeServerDoc function. The resources for the document are freed when 
_ the library calls the Release function. The server should not wait for the Release 
function by entering a message-dispatch loop after calling OleRevokeServerDoc. 
(A server should never enter aes oe sespalch loops while processus any of 
these functions.) 


_ When a document is closed, the server should free the Senior for the - 
_OLESERVERDOCVTBL structure and associated resources. 
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Function 


SetHostNames 


OLESTATUS SetHostNames(/pDoc, lpszClient, IpszDoc) 
LPOLESERVERDOC IpDoc; 

OLE_LPCSTR I[pszClient; 

OLE_LPCSTR IpszDoc; 


Parameters 


Return Value 


Function 


The SetHostNames function sets the name that should be used for a window title. 
This name is used only for an embedded object, because a linked object has its 
own title. This function is used only for documents that are embedded objects. 


lpDoc 
Points to an OLESERVERDOC structure corresponding to a document that is 
the embedded object for which a name is specified. 


lpszClient 
Points to a null-terminated string spechyins the name of the client. | 


lpszDoc 
Points to a null-terminated string specifying the client’s name for the object. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


SetDocDimensions 


OLESTATUS SetDocDimensions(/pDoc, [pRect) 
LPOLESERVERDOC [pDoc; 
OLE_CONST RECT FAR? [pRect; 


Parameters 


Return Value 


The SetDocDimensions function gives the server the rectangle on the target 
device for which the object should be formatted. This function is relevant only for 
documents that are embedded objects. 


lpDoc 
Points to the OLESERVERDOC structure corresponding to the document that 
is the embedded object for which the target size is specified. 


lpRect 
Points to a RECT structure containing the target size of the object, in 
MM_HIMETRIC units. (In the MM_HIMETRIC mapping mode, the positive y- 
direction is up.) 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


Function 
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GetObject 


OLESTATUS GetObject(/pDoc, Ipszltem, IplpObject, IpClient) 
LPOLESERVERDOC I[pDoc; 

OLE_LPCSTR IpszItem; 

LPOLEOBJECT FAR® [plpObject; 

LPOLECLIENT /pClient; 


Parameters 


Return Value 


Comments 


The GetObject function requests the server to create an OLEOBJ ECT structure. 


IpDoc 
Points to an OLESERVERDOC structure corresponding to this document. 


IpszItem | 
Points to a null-terminated string specifying the name of an item in the 
specified document for which an object structure is requested. If this string is 
set to NULL, the entire document is requested. This string cannot contain a 
slash mark (/). 

lplpObject 
Points to a variable of type LPOLEOBJECT in which the server application 
should return a long pointer to the allocated OLEOBJ ECT structure. 


lpClient | 
Points to an OQLECLIENT structure allocated by the library. The server should 
associate the OLECLIENT structure with the object and use it to hoary! the 
library of changes to the object. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


The server application should allocate and initialize the OLEOBJECT structure, 
associate it with the OLECLIENT structure pointed to by the [pClient parameter, 


_ and return a pointer to the OLEOBJECT structure through the /plpObject argu- 
- ment. 7 


The library calls the GetObject function to associate a client with the part of the 
document identified by the [psz/tem parameter. When a client has been associated 
with an object by this function, the server can send notifications to the client. 


Applications should be prepared to handle multiple calls to GetObject for a given 


object. This entails creating multiple OLECLIENT structures and sending notifi- 


cations to each of these structures when appropriate. Multiple calls to GetObject 
are possible because some client applications that implement object linking and 
embedding (OLE) by using dynamic data exchange (DDE) rather than the OLE 
dynamic-link libraries may use both NULL and an actual item name for the 
[pszltem parameter. 
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Function 


Release 


OLESTATUS Release(/pDoc) 
LPOLESERVERDOC IpDoc; 


Parameters 


Return Value 


Function 


The Release function notifies the server when a revoked document has terminated 
conversations and can be destroyed. 


lpDoc 
Points to an OLESERVERDOC structure for which the handle was revoked 
and which can now be released. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


SetColorScheme 


OLESTATUS SetColorScheme(/pDoc, IpPal) 
LPOLESERVERDOC IpDoc; 
OLE_CONST LOGPALETTE FAR* /pPal; 


Parameters 


Return Value 


Comments 


The SetColorScheme function sends the server application the color palette rec- 
ommended by the client application. 


lpDoc 
Points to an OLESERVERDOC structure for which the client application rec- 
ommends a palette. 


lpPal 
Points to a LOGPALETTE structure specifying the recommended palette. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


Server applications are not required to use the palette rsearnisnded by the client 


~ application. 


Before returning from the SetColorScheme function, the server application 
should create a handle to the palette. To do this, the server application should use 


_ the palette pointed to by the /pPal parameter in a call to the CreatePalette func- 
_ tion, as shown in the following example. 


—hpal = CreatePalette(IpPal); 


Function 
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The server can then use the palette handle to refer to the palette. — 


The first palette entry in the LOGPALETTE structure specifies the foreground 
color recommended by the client application. The second palette entry specifies 
the background color. The first half of the remaining palette entries are fill colors, 
and the second half are colors for lines and text. 


Client applications typically specify an even number of palette entries. When there 
is an uneven number of entries, the server should interpret the odd entry as a fill 
color; that is, if there are five entries, three should be interpreted as fill colors and 
two as line and text colors. 


Execute 


OLESTATUS Execute(/pDoc, hCommands) 
LPOLESERVERDOC I[pDoc; 
HGLOBAL hCommands; 


Parameters 


Return Value 


Comments 


The Execute function receives WM_DDE_EXECUTE commands sent by client 
applications. The applications send these commands by calling the OleExecute 
function. 


lpDoc | 
Points to an OLESERVERDOC structure to which the dynamic data exchange 
(DDE) commands apply. 


hCommands 
Identifies memory containing one or more DDE execute commands. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


The server should never free the handle specified in the hCommands parameter. 


364 OLESERVERVTBL 


OLESERVERVTBL 


Function 


d#Hinclude <ole.h> 


typedef struct _OLESERVERVTBL { /* osv ¥*/ 
OLESTATUS (CALLBACK* Open) (LPOLESERVER, LHSERVERDOC, 
OLE_LPCSTR, LPOLESERVERDOC FAR*); 

OLESTATUS (CALLBACK* Create)(LPOLESERVER, LHSERVERDOC, 
OLE_LPCSTR, OLE_LPCSTR, LPOLESERVERDOC FAR*); 
OLESTATUS (CALLBACK* CreateFromTemplate)(LPOLESERVER, 

LHSERVERDOC, OLE_LPCSTR, OLE_LPCSTR, OLE_ LPCSTR, 
LPOLESERVERDOC FAR); 
OLESTATUS (CALLBACK* Edit) (LPOLESERVER, LHSERVERDOC, 
OLE_LPCSTR, OLE_LPCSTR, LPOLESERVERDOC FAR#*); 
OLESTATUS (CALLBACK* Exit) (LPOLESERVER) ; 
OLESTATUS (CALLBACK* Release) (LPOLESERVER) ; 
OLESTATUS (CALLBACK* Execute) (LPOLESERVER, HGLOBAL); 


} OLESERVERVTBL; 


The OLESERVERVTBL structure points to functions that manipulate a server. 
After a server application creates this structure and an OLESERVER structure, 


the server library can perform operations on the server application. 


Every function except Release can return OLE_BUSY. 


Open 


OLESTATUS Open(lpServer, [hDoc, lpszDoc, lplpDoc) 
LPOLESERVER [pServer; 

LHSERVERDOC [hDoc; 

OLE_LPCSTR IpszDoc; 

LPOLESERVERDOC FAR? [plpDoc; 


Parameters 


The Open function opens an existing file and prepares to edit the contents. A 
server typically uses this function to open a linked object for a client application. 


[pServer | 7 
Points to an OLESERVER structure identifying the server. 


lhDoc 
Identifies the document. The library uses this handle internally. 


IpszDoc , 
Points to a null-terminated string specifying the siaanent name of the docu- 


ment to be opened. Typically this string is a path, but for some applications it 
might be further qualified. For example, the string might specify a particular 


table in a database. 


Return Value 
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[plpDoc 
Points to a variable of type LPOLESERVERDOC in which the server applica- 
tion returns a long pointer to the OLESERVERDOC structure it has created in 
response to this function. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


Comments When the library calls this function, the server application opens a specified docu- 
ment, allocates and initializes an OLESERVERDOC structure, associates the 
library’s handle with the document, and returns the address of the structure. The 
server does not show the document or its window. 

Function Create 

OLESTATUS Create(IpServer, lhDoc, lpszClass, lpszDoc, lplpDoc) 

LPOLESERVER IpServer; 

LHSERVERDOC [hDoc; 


OLE_LPCSTR IpszClass; 
OLE_LPCSTR IpszDoc; 
LPOLESERVERDOC FAR¢* IpipDoc; 


Parameters 


Return Value 


The Create function makes a new object that is to be embedded in the client appli- 
cation. The /pszDoc parameter identifies the object but should not be used to 
create a file for the object. 


[pServer 
Points to an OLESERVER structure identifying the server. 


~ [ThDoc 


Identifies the document. The library uses this handle internally. 


lpszClass | 
Points to a null-terminated string specifying the class of document to create. 


[pszDoc 
Points to a null-terminated string specifying a name for the ocumment to be 
created. This name can be used to identify the document in window titles. 
[plpDoc 
Points to a variable of type LPOLESERVERDOC in which the server applica- 
tion should return a long pointer to the created ake structure. 


The return value i is OLE_OK if the function is successful. Otherwise, it is an error 
value. 
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When the library calls this function, the server application creates a document of a 


Comments 
specified class, allocates and initializes an OLESERVERDOC structure, associ- 
ates the library’s handle with the document, and returns the address of the struc- 
ture. This function opens the created document for editing and embeds it in the 
client when it is updated or closed. : 
Server applications often Gack changes to the document specified in this function, 
so that the user can be prompted to save changes when necessary. 

Function CreateFromTemplate © 

OLESTATUS CreateFromTemplate(/pServer, lhDoc, lpszClass, lpszDoc, lpszTemplate, IplpDoc) 

LPOLESERVER [pServer; 

LHSERVERDOC [hDoc; 


OLE_LPCSTR [pszClass; 
OLE_LPCSTR [pszDoc; 
OLE_LPCSTR [pszTemplate; 
LPOLESERVERDOC FAR* [plpDoc; 


Parameters 


The CreateFromTemplate function creates a new document that is initialized 
with the data in a specified file. The new document is opened for editing by this 
function and embedded in the client when it is updated or closed. 


IpServer 
Points to an OLESERVER structure identifying the server. 


[hDoc | 
Identifies the scuieil The library uses this handle internally. 


lpszClass 
Points to a null-terminated string specifying the class of document to create. 


IpszDoc 
Points to a null-terminated string specifying a name for the document to be 
created. This name need not be used by the server application but can be used 
in window titles. 


lpszTemplate 
Points to a null- earcamic string specifying the permanent name of the docu- 
ment to use to initialize the new document. Typically this string is a path, but 
for some applications it might be further qualified. For example, the string 
_ might specify a particular table in a database. 


lplpDoc 
Points to a variable of type LPOLESERVERDOC in which the server applica- 
tion should return a long pointer to the created OLESERVERDOC structure. 


Return Value 
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The return value is OLE_OK if the function is successful. Otherwise, it is an error — 
value. 


Comments When the library calls this function, the server application creates a document of a 
specified class, allocates and initializes an OLESERVERDOC structure, associ- 
ates the library’s handle with the document, and returns the address of the struc- 
ture. 

A server application often tracks changes to the document specified in this func- 
tion, so that the user can be prompted to save changes when necessary. 

Function Edit 

OLESTATUS Edit(/pServer, lhDoc, lpszClass, lpszDoc, lplpDoc) 

LPOLESERVER [pServer; 

~LHSERVERDOC [hDoc; 


OLE_LPCSTR I[pszClass; 
OLE_LPCSTR IpszDoc; 
LPOLESERVERDOC FAR* IplpDoc; 


Parameters 


Return Value 


The Edit function creates a document that is ‘vitalived with data retrieved by a 
subsequent call to the SetData function. The object is embedded in the client appli- 
cation. The server does not show the document or its window. 


lpServer 
Points to an OLESERVER structure identifying the server. 


lhDoc 
Identifies the document. The library uses this handle internally. 


IpszClass 
Points to a null-terminated string specifying the class of document to create. 


lpszDoc 
Points to a null-terminated string specifying a name for the scarieal to be 
created. This name need not be used by the server application but may be 
used—for example, in a window title. 

lplpDoc 
Points to a variable of type LPOLESERVERDOC in which the server eee 
tion should return a long pointer to the created OLESERVERDOC structure. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 7 
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Comments 


Function 


When the library calls this function, the server application creates a document of a 
specified class, allocates and initializes an OLESERVERDOC structure, associ-_ 
ates the library’s handle with the document, and returns the address of the struc- 
ture. 


The document created by the Edit function retrieves the initial data from the client 
in a subsequent call to the SetData function. The user can edit the document after 
the data has been retrieved and the library has used either the Show function in the 
OLEOBJECTVTBL structure or the DoVerb function with an Edit verb to show 
the document to the user. 


Exit 


OLESTATUS Exit(/pServer) 
LPOLESERVER /pServer; 


Parameters 
Return Value 


Comments 


Function 


The Exit function instructs the server application to close documents and ane 


[pServer 
Points to an OLESERVER structure identifying the server. 


The return value is OLE _OK if the function is successful. Otherwise, it is an error 
value. 


The server library calls the Exit function to instruct a server application to termi- 
nate. If the server application has no open documents when the Exit function is | 
called, it should call the OleRevokeServer function. 


Release 


OLESTATUS Release(/pServer) 
LPOLESERVER [pServer; 


Parameters 


Return Value 


The Release function notifies a server that all connections to it have closed and 
that it is safe to quit. 


[pServer 
Points to an OLESERVER structure identifying the server. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 


| value. | 


Comments 


Function 
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The server library calls the Release function when it is safe for a server to quit. 
When a server application calls the OleRevokeServer function, the application 
must continue to dispatch messages and wait for the library to call the Release 

function before quitting. 


When the server is invisible and the library calls Release, the server must exit. 
(The only exception is when an application supports multiple servers; in this case, 
an invisible server is sometimes not revocable when the library calls Release.) If 
the server has no open documents and it was started with the /Embedding option 
(indicating that it was started by a client application), the server should exit when 
the library calls the Release function. If the user has explicitly loaded a document 
into a single-instance multiple document interface server, however, the server 
should not exit when the library calls Release. Typically, a single-instance server 
is a multiple document interface (MDI) server. 


All registered server structures must be released before a server can quit. 


A server can call the PostQuitMessage function inside the Release function. © 


Execute 


| OLESTATUS Execute(/pServer, hCommands) 
~ LPOLESERVER IpServer; 
HGLOBAL hCommands; 


Parameters © 


Return Value — 


Comments | 


The Execute function receives WM _DDE_ EXECUTE commands sent by client 
applications. The applications send these commands by calling the OleExecute 
function. | 


IpServer 


Points to an OLESERVER structure identifying the server. 


hCommands 
Identifies memory containing one or more dynamic data exchange (DE) ex- 
ecute commands. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 


value. 


The server r should never free the handle specified i in the hCommands parameter. 
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OLESTREAM 


d#tinclude <ole.h> 


typedef struct _OLESTREAM { /* ostr */ 
LPOLESTREAMVTBL Ipstbl; 


-} OLESTREAM: 


Members 


OLESTREAMVTBL 


Comments 


The OLESTREAM structure points to an OLESTREAMVTBL structure that 
provides stream input and output functions. These functions are used by the client 
library for stream operations on objects. The OLESTREAM structure is allocated 
and initialized by client applications. 


Ipstbl 
Points to an OLESTREAMVTBL structure. 


dEinclude <ole.h> 


typedef struct _OLESTREAMVTBL { /* ostrv */ 

DWORD (CALLBACK* Get)(LPOLESTREAM, void FAR*, DWORD); 

DWORD (CALLBACK* Put)(LPOLESTREAM, OLE_CONST void FAR*, DWORD); 
} OLESTREAMVTBL; 


The OLESTREAMVTBL structure points to functions the client library uses for 
stream operations on objects. This structure is allocated and initialized by client ap- 
plications. | 


The stream is valid only for the duration of the function to which it is passed. The 
library obtains everything it requires while the stream is valid. 


The return values for the stream functions may indicate that an error has occurred, 
but these values do not indicate the nature of the error. The client application is re- 
sponsible for any required error-recovery operations. 


A client application can use these functions to provide variations on the standard 
stream procedures; for example, the client could change the permanent storage of 
some objects so that they were stored in a database instead of the client document. 


Function 
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Get 


DWORD Get(lpstream, IpszBuf, cbbuf) 
LPOLESTREAM Ipstream; 


void FAR®* IpszBuf; 


DWORD chbuf; 


Parameters 


Return Value 


Comments 


Function 


The Get function gets data from the specified stream. 


lpstream 
Points to an OLESTREAM structure allocated by the client. 


lpszBuf 
Points to a buffer to fill with data from the stream. 


cbbuf 
Specifies the number of bytes to read into the buffer. 


The return value is the number of bytes actually read into the buffer if the function 
is successful. If the end of the file is encountered, the return value is zero. A nega- 
tive return, value indicates that an error occurred. , 


The value specified by the cbbuf parameter can be larger than 64K. If the client ap- 
plication uses a stream-reading function that is limited to 64K, it should call that 
function repeatedly until it has read the number of bytes specified by cbbuf. When- 
ever the data size is larger than 64K, the pointer to the data buffer is always at the 
beginning of the segment. 


Put 


DWORD Put(ipstream, IpszBuf, cbbuf) 
LPOLESTREAM lIpstream; 
OLE_CONST void FAR®* pszBuf: 


~ DWORD cbbuf; 


Parameters 


The Put function puts data into the spreied stream. 


lpstream — 

Points to an OLESTREAM structure allocated by the client. 
lpszBuf 

Points to a buffer from which to write data into the stream. 


cbbuf | 
Specifies the number of bytes to write into the stream. 
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Return Value 


Comments 


OLETARGETDEVICE 


Members 


The return value is the number of bytes actually written to the stream. A return 
value less than the number specified in the cbbuf parameter indicates that either 
there was insufficient space in the stream or an error occurred. 


The value specified by the cbbuf parameter can be greater than 64K. If the client 
application uses a stream-writing function that is limited to 64K, it should call that 
function repeatedly until it has written the number of bytes specified by cbbuf. 
Whenever the data size is greater than 64K, the pointer to the data buffer is always 
at the beginning of the segment. 


4#Finclude <ole.h> 


typedef struct _OLETARGETDEVICE { 
UINT otdDeviceNameOffset; 
UINT otdDriverNameOffset; 
UINT otdPortNameOffset; 
UINT otdExtDevmodeOffset; 
UINT otdExtDevmodeSize; 
UINT otdEnvironmentOffset; 
UINT otdEnvironmentSize; 
BYTE otdData[1]; 

} OLETARGETDEVICE; 


The OLETARGETDEVICE structure contains information about the target 
device that a client application is using. Server applications can use the informa- 
tion in this structure to change the rendering of an object, if necessary. A client ap- 
plication provides a handle to this structure in a call to the OleSetTargetDevice 
function. 


otdDeviceNameOffset 
Specifies the offset from the beginning of the array to the name of the device. 


otdDriverNameOffset | 
Specifies the offset from the beginning of the array to the name of the device 
driver. | 


Comments 


See Also 
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otdPortNameOffset | 
Specifies the offset from the beginning of the array to the name of the port. 


otdExtDevmodeOffset _ 
Specifies the offset from the beginning of the array to a DEVMODE structure 
retrieved by the ExtDeviceMode function. 


otdExtDevmodeSize 
Specifies the size of the DEVMODE structure whose offset is specified by the 
otdExtDevmodeOffset member. 


otdEnvironment Offset | 
Specifies the offset from the beginning of the array to the device environment. 


otdEnvironmentSize 


Specifies the size of the environment whose offset is specified by the 
otdEnvironmentOffset member. 


otdData | 
Specifies an array of bytes containing data for the target device. 


The otdDeviceNameOffset, otdDriverNameOffset, and otdPortNameOffset 
members should be null-terminated. : 


In Windows 3.1, the ability to connect multiple printers to one port has made 
the environment obsolete. The environment information retrieved by the 
GetEnvironment function can occasionally be incorrect. To ensure that the 
OLETARGETDEVICE structure is initialized correctly, the application 
should copy information from the DEVMODE structure retrieved by a 

call to the ExtDeviceMode function to the environment posiuen of the | 
OLETARGETDEVICE structure. 


OleSetTargetDevice 
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OPENFILENAME 


Members 


#Hinclude <commdlg.h> 


typedef struct tagOPENFILENAME { /* ofn */ 


DWORD 
HWND 
HINSTANCE 
LPCSTR 
LPSTR 
DWORD 
DWORD 
LPSTR 
DWORD 
LPSTR 
DWORD 
LPCSTR 
LPCSTR 
DWORD 
UINT 
UINT 
LPCSTR 
LPARAM 
UINT 
LPCSTR © 


} OPENFILENAME; 


1StructSize; 
hwndOwner; 
hInstance; 
IpstrFilter; 
lTpstrCustomFilter; 
nMaxCustFilter; 
nFilterIndex; 
lpstrFile; 

nMaxFile; 
TpstrFileTitle; 
nMaxFileTitle; 
lpstrinitialDir; 
IpstrTitle; : 
Flags; 

nFileOffset; 
nFileExtension; 
lpstrDefExt; 
1CustData; 

(CALLBACK *1pfnHook) CHWND, UINT, WPARAM, LPARAM); 
lpTemplateName; 


The OPENFILENAME structure contains information that the system uses to ini- 
tialize the system-defined Open dialog box or Save dialog box. After the user 
chooses the OK button to close the dialog box, the system returns information 
about the user’s selection in this structure. 


IStructSize 


Specifies the length of the structure, in bytes. This member is filled on input. 


hwndOwner 


Identifies the window that owns the dialog box. This member can be any valid | 
window handle, or it should be NULL if the dialog box is to have no owner. 


If the OFN_SHOWHELY?P flag is set, hwndOwner must identify the window 
that owns the dialog box. The window procedure for this owner window re- 
ceives a notification message when the user chooses the Help button. 

(The identifier for the notification message is the value returned by the 
Register WindowMessage function when HELPMSGSTRING is passed 

as its argument.) 


This member is filled on input. 
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hInstance | 
Identifies a data block that contains a dialog box template specified 
by the lpTemplateName member. This member is used only if the 
Flags member specifies the OFN_ENABLETEMPLATE or the 
OFN_ENABLETEMPLATEHANDLE flag; otherwise, this member 
is ignored. 


This member is filled on input 


IpstrFilter 
Points to a buffer containing one or more pairs of null-terminated strings speci- 
fying filters. The first string in each pair describes a filter (for example, “Text 
Files”); the second specifies the filter pattern (for example, “*.txt’). Multiple fil- 
ters can be specified for a single item; in this case, the semicolon (;) is used to 
separate filter pattern strings—for example, “*.txt;*.doc;*.bak’’. The last string 
in the buffer must be terminated by two null characters. If this parameter is 
NULL, the dialog box does not display any filters. The filter strings must be in 
the proper order—the system does not change the order. 


This member is filled on input. 


— IpstrCustomFilter | 

Points to a buffer containing a pair of user-defined strings that specify a filter. 
The first string describes the filter, and the second specifies the filter pattern 

(for example, “WinWord”, “*.doc”). The buffer is terminated by two null char- — 
acters. The system copies the strings to the buffer when the user chooses the 

OK button to close the dialog box. The system uses the strings as the initial fil- 
ter description and filter pattern for the dialog box. If this parameter is NULL, _ 
the dialog box lists (but does not save) user-defined filter strings. 


nMaxCustFilter 
Specifies the size, in bytes, of the buffer identified by the IpstrCustomFilter 
~ member. This buffer should be at least 40 bytes long. This parameter is ignored 
if the IpstrCustomFilter member is NULL. 


: This member is filled on input. 


nFilterIndex 

Specifies an index into the buffer pointed to by the IpstrFilter member. T he 
system uses the index value to obtain a pair of strings to use as the initial filter 
description and filter pattern for the dialog box. The first pair of strings has an 

index value of 1. When the user chooses the OK button to close the dialog box, 

_ the system copies the index of the selected filter strings into this location. 
If the nFilterIndex member is 0, the filter in the buffer pointed to by the 

_ IpstrCustomFilter member is used. If the nFilterIndex member is 0 and the 
IpstrCustomFilter member is NULL, the system uses the first filter in the 
buffer pointed to by the IpstrFilter member. If each of the three members is _ 
either 0 or NULL, the system does not use any filters and does not show any 
files in the File Name list box of the dialog box. | . 
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IpstrFile | 
Points to a buffer that specifies a filename used to initialize the File Name edit 
control. If initialization is not necessary, the first character of this buffer must 
be NULL. When the GetOpenFileName or GetSaveFileName function re- 
turns, this buffer contains the complete location and name of the selected file. 


If the buffer is too small, the dialog box procedure copies the required size into 
this member and returns 0. To retrieve the required size, cast the IpstrFile mem- 
ber to type LPWORD. The buffer must be at least three bytes to receive the 
required size. When the buffer is too small, the CommDIgExtendedError 
function returns the FNERR BUFFERTOOSMALL value. 


nMaxFile 
Specifies the size, in bytes, of the buffer pointed to by the IpstrFile member. 
The GetOpenFileName and GetSaveFileName functions return FALSE if the 
buffer is too small to contain the file information. The buffer should be at least 
256 bytes long. If the IpstrFile member is NULL, this member is ignored. 


This member is filled on input. 


IpstrFileTitle 
Points to a buffer that receives the title of the selected file. This buffer receives 
the filename and extension but no path information. An application should use 
this string to display the file title. If this member is NULL, the function does 
not copy the file title. This member is filled on output. 


nMaxFileTitle 
Specifies the maximum length, in bytes, of the string that can be copied into the 
IpstrFileTitle buffer. This member is ignored if IpstrFileTitle is NULL. This 
member is filled on input. 


IpstrInitialDir 
Points to a string that specifies the initial file directory. If this member is _ 
NULL, the system uses the current directory as the initial directory. (If the 
IpstrFile member contains a string that specifies a valid path, the common 
dialog box procedure will use the path specified by this string instead of the 
path specified by the string to which IpstrInitialDir points.) 


This member is filled on input. 

IpstrTitle | : 
Points to a string to be placed in the title bar of the dialog box. If this member is 
NULL, the system uses the default title (that is, Save As or Open). This mem- 
ber is filled on input. 

Flags | | | 

Specifies the dialog box initialization flags. This member may be a combination 

of the following values: 
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Value Meaning 


OFN_ALLOWMULTISELECT 


Specifies that the File Name list box is to allow mul- 
tiple selections. When this flag is set, the IpstrFile 
member points to a buffer containing the path to the 
current directory and all filenames in the selection. 
The first filename is separated from the path by a 
space. Each subsequent filename is separated by 

one space from the preceding filename. Some of the 
selected filenames may be preceded by relative 
paths; for example, the buffer could contain some- 
thing like this: 

c:\files file1.txt file2.txt ..\bin\file3.txt 


OFN_CREATEPROMPT Causes the dialog box procedure to generate a 
message box to notify the user when a specified 
file does not currently exist and to make it 
possible for the user to specify that the file | 
should be created. (This flag automatically 
sets the OFN_PATHMUSTEXIST and 
OFN_FILEMUSTEXIST flags.) 


OFN_ENABLEHOOK Enables the hook function specified in the 
IpfnHook member. . 


OFN_ENABLETEMPLATE — Causes the system to use the dialog box template 
| identified by the hInstance and IpTemplateName 
members to create the dialog box. 


OFN_ENABLETEMPLATEHANDLE 


Indicates that the hInstance member identifies a 
data block that contains a pre-loaded dialog box 
template. The system ignores the IlpTemplateName 
member if this flag is specified. 


OFN_EXTENSIONDIFFERENT 


Indicates that the extension of the returned filename 
is different from the extension specified by the 
IpstrDefExt member. This flag is not set if 
IpstrDefExt is NULL, if the extensions match, or if 
the file has no extension. This flag can be set on out- 
put. 


OFN_FILEMUSTEXIST Specifies that the user can type only the names of 
existing files in the File Name edit control. If this 
flag is set and the user types an invalid filename in 
the File Name edit control, the dialog box proce- 
dure displays a warning in a message box. (This 
flag also causes the OFN_PATHMUSTEXIST flag 
to be set.) | . 


OFN_HIDEREADONLY Hides the Read Only check box. 
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Value Meaning 


OFN_NOCHANGEDIR Forces the dialog box to reset the current directory 
to what it was when the dialog box was created. 


. OFN_NOREADONLYRETURN 


Specifies that the file returned will not have the 
Read Only attribute set and will not be in a write- 
protected directory. 


OFN_NOTESTFILECREATE _ Specifies that the file will not be created before the 
dialog box is closed. This flag should be set if the 
application saves the file on a create-no-modify net- 
work share point. When an application sets this 
flag, the library does not check against write protec- 
tion, a full disk, an open drive door, or network pro- 
tection. Therefore, applications that use this flag 
must perform file operations carefully—a file can- 
not be reopened once it is closed. 


OFN_NOVALIDATE Specifies that the common dialog boxes will 
allow invalid characters in the returned filename. 
Typically, the calling application uses a hook 
function that checks the filename using the 
FILEOKSTRING registered message. If the text in 
the edit control is empty or contains nothing but 
spaces, the lists of files and directories are updated. 
If the text in the edit control contains anything else, 
the nFileOffset and nFileExtension members are 
set to values generated by parsing the text. No de- | 
fault extension is added to the text, nor is text 
copied to the IpstrFileTitle buffer. 


If the value specified by the nFileOffset mem- 
ber is negative, the filename is invalid. If the 
value specified by nFileOffset is not negative, 
_ the filename is valid, and nFileOffset and 
nFileExtension can be used as if the | 
OFN_NOVALIDATE flag had not been set. 


OFN_OVERWRITEPROMPT _ Causes the Save As dialog box to generate a mes- 
~ sage box if the selected file already exists. The user 
must confirm whether to overwrite the file. 


OFN_PATHMUSTEXIST Specifies that the user can type only valid paths. If 
af cige 7 this flag is set and the user types an invalid path in 
the File Name edit control, the dialog box proce- 
dure displays a warning in a message box. _ 


OFN_READONLY Causes the Read Only check box to be initially 
checked when the dialog box is created. When the 
user chooses the OK button to close the dialog box, 
the state of the Read Only check box is specified by 
this member. This flag can be set on input and 
output. : 
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Value — Meaning 


OFN_SHAREAWARE Specifies that if a call to the OpenFile function has 
failed because of a network sharing violation, the 
error is ignored and the dialog box returns the given 
filename. If this flag is not set, the registered mes- 
sage for SHAREVISTRING is sent to the hook 
function, with a pointer to a null-terminated string 
for the path name in the /Param parameter. The 
hook function responds with one of the following 
values: | 


Value Meaning 


OFN_SHAREFALLTHROUGH 


Specifies that the filename is re- 
turned from the dialog box. 


OFN_SHARENOWARN 
Specifies no further action. 
OFN_SHAREWARN 
Specifies that the user receives the 
standard warning message for this 
error. (This is the same result as if 
| there were no hook function.) 
7 This flag may be set on output. 
OFN_SHOWHELP Causes the dialog box to show the Help push but- 


ton. The hwndOwner must not be NULL if this op- 
tion is specified. 


These flags may be set when the structure is initialized, except where specified. 


-nFileOffset 
Specifies a zero-based offset from the beginning of the path to the filename — 
specified by the string in the buffer to which IpstrFile points. For example, if 
IpstrFile points to the string, “c:\dir1\dir2 \ file.ext’, this member contains the 
value 13. 7 


This member is filled on output. 


nFileExtension 
Specifies a zero-based offset from the beginning of the path to the filename 
extension specified by the string in the buffer to which IpstrFile points. For 
example, if IpstrFile points to the following string, “c:\dir1\dir2 \ file.ext’, 
this member contains the value 18. If the user did not type an extension and 
IpstrDefExt is NULL, this member specifies an offset to the terminating null 
character. If the user typed a period (.) as the last character in the filename, this 
member is 0. | | 


This member is filled on output. 
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IpstrDefExt 


Points to a buffer that contains the default extension. The GetOpenFileName 
or GetSaveFileName function appends this extension to the filename if the 
user fails to enter an extension. If the filename with the default extension is not 
found, GetOpenFileName or GetSaveFileName attempts to find the file by 
using the name exactly as the user typed it. This string can be any length, but 
only the first three characters are appended. The string should not contain a pe- 


_ riod (.). If this member is NULL and the user fails to type an extension, no ex- 


tension is appended. This member is filled on input. 


ICustData 


Specifies application-defined data that the system passes to the hook function 
pointed to by the IpfnHook member. The system passes a pointer to the OPEN- 
FILENAME structure in the /Param parameter of the WM_INITDIALOG 
message; this pointer can be used to retrieve the I|CustData member. 


IpfnHook 


Points to a hook function that processes messages intended for the 

dialog box. To enable the hook function, an application must specify the 
OFN_ENABLEHOOK flag in the Flags member; otherwise, the system 
ignores this structure member. The hook function must return zero to 

pass a message that it didn’t process back to the dialog box procedure in 
COMMDLG.DLL. The hook function must return a nonzero value to prevent 
the dialog box procedure in COMMDLG. DLL from processing a message it 
has already processed. 


This member is filled on input. 


IpTemplateName 


Points to a null-terminated string that specifies the name of the resource file for 
the dialog box template that is to be substituted for the dialog box template in 
COMMDLG.DLL. An application can use the MAKEINTRESOURCE macro 
for numbered dialog box resources. This member is used only if the Flags mem- 
ber specifies the OFN_ENABLETEMPLATE flag; otherwise, this member is 
ignored. 


This member is filled o on anput 


GetOpenFileName, GetSaveFileName 


OUTLINETEXTMETRIC 


typedef struct tagOUTLINETEXTMETRIC { 


Members 


UINT 
TEXTMETRIC 
BYTE 
PANOSE 
UINT 
UINT 
UINT 
UINT 
UINT 
UINT 
INT 
INT 
UINT 
UINT 
UINT 
RECT 
INT 
INT 
UINT 
UINT 
POINT 
POINT 
POINT 
POINT 
UINT 
INT 
INT 
UINT 
PSTR 
PSTR 
PSTR 
PSTR 
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[ 3.1 | 


otmSize; 
otmTextMetrics; 
otmFiller; 
otmPanoseNumber; 
otmfsSelection; 
otmfsType; 
otmsCharSlopeRise; 
otmsCharSlopeRun; 
otmItalicAngle; 
otmEMSquare; 
otmAscent; 
otmDescent; 
otmLineGap; 
otmsXHeight; 
otmsCapEmHeight; 
otmrcFontBox; 
otmMacAscent; 
otmMacDescent; 
otmMacLineGap; 
otmusMinimumPPEM; 
otmptSubscriptSize; 
otmptSubscriptOffset; 
otmptSuperscriptSize; 
otmptSuperscriptOffset; 
otmsStrikeoutSize; 
otmsStrikeoutPosition; 
otmsUnderscorePosition; 
otmsUnderscoreSize; 
otmpFamilyName; 
otmpFaceName; 
otmpStyleName; 
otmpFullName; 


} Meee ERIN EES 


The OUTLINETEXTMETRIC structure contains metrics describing a TrueType 


font. | 


—otmSize 


Specifies the size, in bytes, of the erg era structure. 


otmTextMetrics 


Specifies a TEXTMETRIC structure containing further information about the 


font. 
otmFiller 


Specifies a value that causes the structure to be byte-aligned. 
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otmPanoseNumber 
Specifies the Panose number for this font. 


—otmfsSelection 
Specifies the nature of the font pattern. This member can be a combination of 
the following bits: 


Bit Meaning 


Italic 
Underscore 
Negative 
Outline 
Strikeout 
Bold 


Mm” BR WO NO —= CO 


otmfsType 
Specifies whether the font is licensed. Licensed fonts may not be modified or 
exchanged. If bit 1 is set, the font may not be embedded in a document. If bit 1 
is clear, the font can be embedded. If bit 2 is set, the embedding is read-only. 


otmsCharSlopeRise 
Specifies the slope of the cursor. This value is 1 if the slope is vertical. Applica- 
tions can use this value and the value of the otmsCharSlopeRun member to 
create an italic cursor that has the same slope as the main italic angle (specified 
by the otmItalicAngle member). 


otmsCharSlopeRun 
Specifies the slope of the cursor. This value is zero if the slope is vertical. Ap- 
plications can use this value and the value of the otmsCharSlopeRise member 
to create an italic cursor that has the same slope as the main italic angle 
(specified by the otmItalicAngle member). 


otmItalicAngle 
Specifies the main italic angle of the font, in counterclockwise degrees from 
vertical. Regular (roman) fonts have a value of zero. Italic fonts typically havea © 
negative italic angle (that is, ey lean to the right). 


otmEMSquare 
Specifies the number of logical units defining the x- or seainenson of theem | 
square for this font. (The number of units in the x- and y-directions are always . 
the same for an em square.) eon 


otmAscent 
Specifies the maximum distance caarahiers in this font extend above the base 
line. This is the typographic ascent for the font. 


—otmDescent 
Specifies the maximum distance cheers in this font extend ice the base 
line. This is the typographic descent for the font. 
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otmLineGap 
Specifies typographic line spacing. 


otmsX Height 
Not supported. 


otmsCapEmHeight 
Not supported. 


otmrcFontBox | 
Specifies the bounding box for the font. 


otmMacAscent 
Specifies the maximum distance characters in this font extend above the base 
line for the Macintosh. 


otmMacDescent : 


Specifies the maximum distance characters in this font extend below the base 
line for the Macintosh. 


otmMacLineGap 
Specifies line-spacing information for the Macintosh. 


otmusMinimumPPEM 
Specifies the smallest recommended size for this font, in pixels per em-square. 


otmptSubscriptSize 
Specifies the recommended horizontal and vertical size for subscripts in this 
font. , 


otmptSubscriptOffset 
Specifies the recommended horizontal and vertical offset for subscripts in this 
font. The subscript offset is measured from the character origin to the origin of 
the subscript character. . 


otmptSuperscriptSize 
Specifies the recommended horizontal and vertical size for superscripts in this 
font. 


otmptSuperscriptOffset 
Specifies the recommended horizontal and vertical offset for superscripts in this 
font. The subscript offset is measured from the character base line to the base 
line of the superscript character. 


otmsStrikeoutSize 
Specifies the width of the strikeout stroke for this font. Typically, this i is the 
width of the em-dash for the font. 


otmsStrikeoutPosition 
Specifies the position of the strikeout stroke relative to the base line for this 
font. Positive values are above the base line and negative values are below. 


otmsUnderscorePosition 
Specifies the position of the underscore character for this font. 
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otmsUnderscoreSize 
Specifies the thickness of the underscore character for this font. 


otmpFamilyName | 
Specifies the offset from the beginning of the structure to a string specifying the 
family name for the font. , 


otmpFaceName | 
Specifies the offset from the beginning of the structure to a string specifying the 
face name for the font. (This face name corresponds to the name specified in 
the LOGFONT structure.) | 


otmpStyleName 
Specifies the offset from the beginning of the structure to a string specifying the 
style name for the font. 


otmpFullName 
Specifies the offset from the beginning of the structure to a string specifying the 
full name for the font. This name is unique for the font and often contains a ver- 
sion number or other identifying information. 


Comments The sizes returned in OUTLINETEXTMETRIC are given in logical units; that 
| is, they depend on the current mapping mode of the specified display context. 


See Also GetOutlineTextMetrics 
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typedef struct tagPAINTSTRUCT { /* ps */ 
HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[16]; 
} PAINTSTRUCT; 


The PAINTSTRUCT stnicture contains information for an application. This infor- 
mation can be used to paint the client area of a window owned by that application. 


Members  hde 
Identifies the display context to be used for painting. 
fErase 


Specifies whether the background needs to be redrawn. This value is nonzero if 
the application should redraw the background. The application is responsible 
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for drawing the background if a window class is created without a background 
brush. For more information, see the description of the hbrBackground mem- 
ber of the WNDCLASS structure. 


rcPaint 
Specifies the upper-left and iowacaisti corners of the rectangle in which the 


painting is requested. 


_fRestore 
Reserved; used internally by Windows. 


fIncUpdate 
Reserved; used internally by Windows. 


| rgbReserved | 
Reserved (reserved memory object used internally by Windows). 


See Also - BeginPaint, WNDCLASS 


PALETTEENTRY - ey 


typedef struct tagPALETTEENTRY { /* pe */ 
BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 
 } PALETTEENTRY; 


The PALETTEENTRY structure specifies the color and usage of an entry ina 
logical color palette. A logical palette is defined by a LOGPALETTE structure. 


_ Members © | peRed | | 
Specifies the intensity of red for the palette entry color. 


peGreen 
Specifies the case of green for the palette entry color. 


peBlue 
Specifies the intensity of blue for the pases omy éélor. 


peFlags 
Specifies how the palette entry is to be used. The peFlags meee may be set 
to NULL or to one of the following values (specifying NULL informs Win- | 
dows that the palette entry contains an RGB value and that it should be mapped - 


normally): 
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Value Meaning 


PC_EXPLICIT Specifies that the low-order word of the logical palette 
| entry designates a hardware palette index. This flag allows 
the application to show the contents of the palette for the 
display device. 


PC_NOCOLLAPSE Specifies that the color will be placed in an unused entry in 
the system palette instead of being matched to an existing 
color in the system palette. Once this color is in the system 
palette, colors in other logical palettes can be matched to 
this color. If there are no unused entries in the system 
palette, the color is matched normally. 


PC_RESERVED Specifies that the logical palette entry will be used foi 
palette animation. Because the color will frequently 
change, using this flag prevents other windows from 
matching colors to this palette entry. If an unused system- 
palette entry is available, this color is placed in that entry. 
Otherwise, the color will not be available for animation. 


See Also AnimatePalette 


PANOSE [ 3.1 | 


typedef struct tagPANOSE { /* panose */— 
BYTE bFamilyType; 
BYTE bSerifStyle; 
BYTE bWeight; 
BYTE bProportion; 
BYTE bContrast; 
BYTE bStrokeVariation; 
BYTE bArmStyle; 
BYTE bLetterform; 
BYTE bMidline; 
BYTE bXHeight; 
} PANOSE; 


The PANOSE structure describes the Panose font-classification values for a True- 
Type font. 
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Members bFamilyType — | 

Specifies the font family. This member can be one of the following values: 
Value Meaning | 
0 Any 

1 No fit 

2 Text and display 

3 Script 

4 Decorative 

5 Pictorial 

bSerifStyle 

Specifies the style of serifs for the font. This member can be one of the follow- 
ing values: | 

Value Meaning 

0 Any 

1 No fit 

2 Cove 

3 Obtuse cove 
4 Square cove 

5 Obtuse square cove 

6 Square 

7 Thin 

8 Bone 

9 Exaggerated 

10 Triangle 

1] Normal sans 

12 Obtuse sans 

13 Perp sans 

14 Flared 


15 Rounded 
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bWeight | 
Specifies the weight of the font. This member can be one of the following 
values: 
Value Meaning 
0 Any 
1 No fit 
2 Very light 
3 Light 
4 Thin 
5 Book 
6 Medium 
7 Demi 
8 Bold 
9 Heavy 
10 Black 
11 Nord 
bProportion 
Specifies the proportion of the font. This member can be one of the following 
values: 
Value Meaning 
0 Any 
1 No fit 
2 Old style 
3 Modern 
4 Even width 
5 Expanded 
6 Condensed 
7 Very expanded 
8 Very condensed 
9 Monospaced 


PANOSE 
bContrast 
_ Specifies the contrast of the font. This member can be one of the following 
values: 
Value Meaning 
0 Any 
1 No fit 
2 None 
3 Very low 
4 Low 
7, Medium low 
6 Medium | 
7 Medium high 
8 High 
9 Very high 
bStrokeVariation 


Specifies the stroke variation for the font. This member can be one of the fol- 
lowing values: : 


Value 


COonHnN NN BP WN =| © 


Meaning 


Any 

No fit 
Gradual/diagonal 
Gradual/transitional 
Gradual/vertical 
Gradual/horizontal © 
Rapid/vertical 
Rapid/horizontal 
Instant/vertical 
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bArmStyle 

Specifies the style for the arms in the font. This member can be one of the fol- — 

lowing values: 

Value Meaning 

0 Any 

1 No fit 

2° Straight arms/horizontal 

3 Straight arms/wedge 

4 Straight arms/vertical 

5 Straight arms/single serif 

6 Straight arms/double serif 

7 Non-straight arms/horizontal 

8 Non-straight arms/wedge 

9 Non-straight arms/Vvertical 

10 Non-straight arms/single serif 

11 Non-straight arms/double serif 
bLetterform 

Specifies the letter form for the font. This member can be one of the following 

values: | 

Value Meaning 

0 Any 

1 No fit 

2 Normal/contact 

3 Normal/weighted 

4 Normal/boxed 

5 Normal/flattened 

6 Normal/rounded 

7 Normal/off-center 

8 Normal/square 

9 Oblique/contact 

10 Oblique/weighted 

11 Oblique/boxed 

12 Oblique/flattened 

13 Oblique/rounded 

14 Oblique/off-center 

15 Oblique/square — 
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bMidline | | 
Specifies the style of the midline for the font. This member can be one of the 
following values: 


Value Meaning 

0 Any 

1 No fit 

2 Standard/trimmed 
—=3 Standard/pointed 

4 Standard/serifed 

5 High/trimmed 

6 High/pointed 

7 High/serifed 

8 7 Constant/trimmed 

9 Constant/pointed 

10 Constant/serifed 

11 | Low/trimmed 

12 Low/pointed 

13 Low/serifed 
bXHeight : 


Specifies the x-height of the font. This member can be one of the following 
values: : <7 OS 


Value Meaning 

0 Any — 

1 No fit 

Ze Constant/small 
3 Constant/standard 
i Constant/large 

5 Ducking/small 

6 Ducking/standard 
7 Ducking/large | 
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POINT 


Members 


See Also 


POINTFX 


-Members 


See Also 


typedef struct tagPOINT { /* pt */ 


int x; 
int y; 
} POINT; 


The POINT structure defines the x- and y-coordinates of a point. 


x 
Specifies the x-coordinate of a point. 


Specifies the y-coordinate of a point. 


ChildWindowFromPoint, PtInRect, WindowFromPoint 


typedef struct tagPOINTFX { 
FIXED x; 
FIXED y; 

} POINTFX; 


The POINTFX< structure contains the coordinates of points that describe 
the outline of a character in a TrueType font. POINTFX is a member of the 


TTPOLYCURVE and TTPOLYGONHEADER structures. 


X 


Specifies the x-component of a point on the outline of a TrueType character. 


Specifies the y-component of a point on the outline of a TrueType character. 


FIXED, TTPOLYCURVE, TTPOLYGONHEADER 
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Members 


#Finclude <commdlg.h> 


typedef struct tagPD { /* pd */ 
DWORD 1StructSize; 
HWND hwndOwner; 
HGLOBAL hDevMode; 
HGLOBAL hDevNames; 


HDC hDC; 

DWORD Flags; 
UINT nFromPage; 
UINT nToPage; 
UINT nMinPage; 
UINT nMaxPage; 
UINT nCopies; 


HINSTANCE hInstance; 
LPARAM 1CustData; 


UINT (CALLBACK* IpfnPrintHook)(HWND, UINT, WPARAM, 
UINT (CALLBACK* 1TpfnSetupHook)(HWND, UINT, WPARAM, 
LPCSTR TpPrintTemplateName; 
LPCSTR ]pSetupTemplateName; 


HGLOBAL hPrintTemplate; 
HGLOBAL hSetupTemplate; 
7 PRINTDLG; 
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[ 3.1 | 


LPARAM) ; 
LPARAM) ; 


The PRINTDLG structure contains information that the system uses to initialize 


the system-defined Print dialog box. After the user chooses the OK button to close | 


the dialog box, the system returns information about the user’s selections in is 


- Structure. 


IStructSize 


Specifies the length of the structure, in bytes. This member is filled on input. 


hwndOwner 


Identifies the window that owns the dialog box. This member can be any valid 
window handle, or it should be NULL if the dialog box is to have no owner. 


If the PD_SHOWHELP flag is set, hwndOwner must identify the window that 
owns the dialog box. The window procedure for this owner window receives a 

notification message when the user chooses the Help button. (The identifier for 
the notification message is the value returned by the Register WindowMessage 


function when HELPMSGSTRING is pasion as its argument.) 


This member is filled on input. 
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hDevMode 


Identifies a movable global memory object that contains a DEVMODE struc- 
ture. Before the PrintDlg function is called, the members in this structure may 
contain data used to initialize the dialog box controls. When the PrintDlg func- 
tion returns, the members in this structure specify the state of each of the dialog 
box controls. 


If the application uses the structure to initialize the dialog box controls, it must 
allocate space for and create the DEVMODE structure. (The application should 
allocate a movable memory object.) 


If the application does not use the structure to initialize the dialog box controls, 
the hDevMode member may be NULL. In this case, the PrintDlg function allo- 
cates memory for the structure, initializes its members, and returns a handle that 


“identifies it. 


If the device driver for the specified printer does not support extended device 
modes, the hDevMode member is NULL when PrintDlg returns. 


If the device name (specified by the dmDeviceName member of the 
DEVMODE structure) does not appear in the [devices] section of WIN.INI, 
the PrintDlg function returns an error. 


The value of hDevMode may change during the execution of the PrintDlg 
function. This member is filled on input and mee 


hDevNames 


Identifies a movable global memory object that contains a DEVNAMES struc- 
ture. This structure contains three strings; these strings specify the driver name, 
the printer name, and the output-port name. Before the PrintDlg function is 
called, the members of this structure contain strings used to initialize the dialog 
box controls. When the PrintDlg function returns, the members of this struc- 
ture contain the strings typed by the user. The calling application uses these 
strings to create a device context or an information context. 


If the application uses the structure to initialize the dialog box controls, it must 
allocate space for and create the DEVMODE data structure. (The application 
should allocate a movable global memory object.) 


If the application does not use the structure to initialize the dialog box controls, 
the hDevNames member can be NULL. In this case, the PrintDlg function allo- 
cates memory for the structure, initializes its members (using the printer name 
specified in the DEVMODE data structure), and returns a handle that identifies 
it. When the PrintDlg function initializes the members of the DEVNAMES 
structure, it uses the first port name that appears in the [devices] section of 
WIN.INI. For example, the function uses “LPT1” as the port name if the follow- 
ing string appears in the [devices] section: 


PCL / HP Laserdet=HPPCL,LPT1:,LPT2: 


If both the hDevMode and hDevNames members are NUE PrintDig speci- 
fies the current default printer for hDevNames. 
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The value of hDevNames may change during the execution of the PrintDlg 
function. This member is filled on input and output. 


hDC 
Identifies either a device context or an information context, depending on 
whether the Flags member specifies the PD_RETURNDC or the 
PD_RETURNIC flag. If neither flag is specified, the value of this member is 
undefined. If both flags are specified, hDC is PD_RETURNDC. 


This member is filled on output. 


Flags | 
Specifies the dialog box initialization flags. This member may be a combination 
of the following values: 


Value Meaning 


PD_ALLPAGES Indicates that the All radio button was selected 
| when the user closed the dialog box. (This value 
is used as a placeholder, to indicate that the 
PD_PAGENUMS and PD_SELECTION flags 
are not set. This value can be set on input and 
output.) | 


PD_COLLATE | Causes the Collate Copies check box to be 
checked when the dialog box is created. When 
the PrintDlg function returns, this flag indicates 
the state in which the user left the Collate 
Copies check box. This flag can be set on input 


| | and output. 
PD_DISABLEPRINTTOFILE Disables the Print to File check box. 
PD_ENABLEPRINTHOOK Enables the hook function specified in the 


IpfnPrintHook member of this structure. 
PD_ENABLEPRINTTEMPLATE 


Causes the system to use the dialog box tem- 
plate identified by the hInstance and IpPrint- 
TemplateName members to create the Print 
dialog box. 


PD_ENABLEPRINTTEMPLATEHANDLE 


Indicates that the hPrintTemplate member iden- 
tifies a data block that contains a pre-loaded 
dialog box template. The system ignores the 
hInstance member if this flag is specified. 


PD_ENABLESETUPHOOK Enables the hook function specified in the 
| IpfnSetupHook member of this structure. 
PD_ENABLESETUPTEMPLATE | 
Causes the system to use the dialog box tem- 
plate identified by the hInstance and IpSetup- 
TemplateName members to create the Print 
Setup dialog box. 
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Value | 


Meaning 


PD_ENABLESETUPTEMPLATEHANDLE 


PD_HIDEPRINTTOFILE 
PD_NOPAGENUMS 


PD_NOSELECTION 
PD_NOWARNING 


PD_PAGENUMS 


PD_PRINTSETUP 


PD_PRINTTOFILE 


PD_RETURNDC 


PD_RETURNDEFAULT 


Indicates that the hSetupTemplate member 
identifies a data block that contains a pre-loaded 
dialog box template. The system ignores the 
hInstance member if this flag is specified. 


Hides and disables the Print to File check box. 


Disables the Pages radio button and the 
associated edit controls. 


Disables the Selection radio button. 


Prevents the warning message from being dis- 
played when there is no default printer. 


Causes the Pages radio button to be selected 
when the dialog box is created. When the 
PrintDlg function returns, this flag is set if the 
Pages button is in the selected state. If neither 
PD_PAGENUMS nor PD_SELECTION is 
specified, the All radio button is in the selected 
State. 


This flag can be set on input and output. 


Causes the system to display the Print Setup 
dialog box rather than the Print dialog box. 


Causes the Print to File check box to be checked 
when the dialog box is created. : 


This flag can be set on input and output. 


Causes the PrintDlg function to return a device 
context matching the selections that the user 
made in the dialog box. The handle to the 
device context is returned in the hDC 

member. If neither PD_RETURNDC nor 
PD_RETURNIC is specified, the hDC parame- 
ter is undefined on output. 


Causes the PrintDlg function to return 
DEVMODE and DEVNAMES structures that 
are initialized for the system default printer. 
PrintDlg does this without displaying a dialog 
box. Both the hDevNames and the hDevMode 


_ members should be NULL; otherwise, the func- 
tion returns an error. If the system default 


printer is supported by an old printer driver 
(earlier than Windows version 3.0), only the 


~ _hDevNames member is returned—the 


hDevMode member is NULL. 


Value 


PD_RETURNIC 


PD_SELECTION 


PD_SHOWHELP 


PD_USEDEVMODECOPIES 
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Meaning 


Causes the PrintDlg function to return an infor- 
mation context matching the selections that the 
user made in the dialog box. The information 
context is returned in the hDC member. If 
neither PD_RETURNDC nor PD_RETURNIC 
is specified, the hDC parameter is undefined on 
output. 


Causes the Selection radio button to be selected 
when the dialog box is created. When the 
PrintDlg function returns, this flag is set if the 
Selection button is in the selected state. If 
neither PD_PAGENUMS nor PD_SELECTION 
is specified, the All radio button is in the 
selected state. 


This flag can be set on input and output. 


Causes the dialog box to show the Help button. 
If this flag is specified, the hwndOwner must 
not be NULL. 


Disables the Copies edit control if a printer 
driver does not support multiple copies. If a 
driver does support multiple copies, setting this 
flag indicates that the PrintDlg function should 
store the requested number of copies in the 
dmCopies member of the DEVMODE struc- 
ture and store the value 1 in the nCopies mem- 
ber of the PRINTDLG structure. 

If this flag is not set, the PRINTDLG structure 
stores the value 1 in the dmCopies member of 
the DEVMODE structure and stores the re- 


quested number of copies in the nCopies 
member of the PRINTDLG structure. 


These flags may be set when the structure is initialized, except where specified. 


nFromPage 


Specifies the initial value for the starting page in the From edit control. When 
the PrintDlg function returns, this member specifies the page at which to begin 
printing. This value is valid only if the PD_PAGENUMS flag is specified. The 
maximum value for this member is OXFFFE; if OxXFFFF is specified, the From 


edit control is left blank. 


This member is filled on input and output. 
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nToPage 
Specifies the initial value for the ending page in the To edit control. When the 
PrintDlg function returns, this member specifies the last page to print. This 
value is valid only if the PD_PAGENUMS flag is specified. The maximum 
value for this member is OXFFFE; if OxXFFFF is specified, me To edit control is 
left blank. 


This member is filled on input and output. 


nMinPage 
Specifies the minimum number of pages that can be specified i in the Pisin and 
To edit controls. This member i is filled on input. 


nMaxPage — 
Specifies the maximum number of pages that can be specified in the From and 
To edit controls. This member is filled on input. 


nCopies 
Before the PrintDlg function is called, this member specifies the value to be 
used to initialize the Copies edit control if the hDevMode member is NULL; 
otherwise, the dmCopies member of the DEVMODE structure contains the 
value used to initialize the Copies edit control. 


When PrintDlg returns, the value specified by this member depends on the ver- 
sion of Windows for which the printer driver was written. For printer drivers 
written for Windows versions earlier than 3.0, this member specifies the num- 
ber of copies requested by the user in the Copies edit control. For printer 
drivers written for Windows versions 3.0 and later, this member specifies the 
number of copies requested by the user if the PD_USEDEVMODECOPIES 
flag was not set; otherwise, this member specifies the value 1 and the actual 
number of copies requested appears in the DEVMODE structure. 


This member 1s filled on input and output. 


instance 
Identifies a data block that contains the pre-loaded dialog box template 
specified by the IlpPrintTemplateName or the IpSetupTemplateName 
member. This member is used only if the Flags member specifies the 
PD_ENABLEPRINTTEMPLATE or PD_ENABLESETUPTEMPLATE flag; 
otherwise, this member is ignored. 


This member is filled on input. 


~ 1CustData | 
Specifies application-defined data that the system passes to the hook function 
identified by the IpfnPrintHook or the IpfnSetupHook member. The system 
passes a pointer to the PRINTDLG structure in the /Param parameter of the 
WM_INITDIALOG message; this pointer can be used to retrieve the lCust- 
Data member. 


See Also 
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IpfnPrintHook 
Points to the exported hook function that processes dialog box messages if the 
application customizes the Print dialog box. This member is ignored unless the 
PD_ENABLEPRINTHOOK flag is specified in the Flags member. 


This member is filled on input. 


IpfnSetupHook 
Points to the exported hook function that processes dialog box messages if the 
application customizes the Print Setup dialog box. This member is ignored un- 
less the PD_ENABLESETUPHOOK flag is specified in the maaee member. 


This member is filled on input. 


IpPrintTemplateName 
Points to a null-terminated string that specifies the dialog box template that is to 
be substituted for the standard dialog box template in COMMDLG. An applica- 
tion must specify the PD_ENABLEPRINTTEMPLATE constant in the Flags 
member to enable the hook function; otherwise, the system ignores this struc- 
ture member. 


This member is filled on input. 


IpSetupTemplateName 


Points to a null-terminated string that specifies the dialog box template that is to 
be substituted for the standard dialog box template in COMMDLG. An applica- 
tion must specify the PD_ENABLEPRINTTEMPLATE constant in the Flags 
member to enable the hook function; otherwise, the system ignores this struc- 
ture member. 


This member is filled on input. 


hPrintTemplate 
Identifies the handle of the global memory object that contains the pre- 
loaded dialog box template to be used instead of the default template in 
COMMDLG.DLL for the Print dialog box. To use the dialog box template, © 
the PD_ENABLEPRINTTEMPLATEHANDLE flag must be set. 


This member is filled on input. 


hSetupTemplate 
Identifies the handle of the global memory object that contains the pre- 
loaded dialog box template to be used instead of the default template in 
COMMDLG.DLL for the Print Setup dialog box. To use the dialog box tem- 
plate, the PD_ENABLEPRINTTEMPLATEHANDLE flag must be set. 


This member is filled on input. 


CreateDC, CreateIC, PrintDlg, DEVMODE, DEVNAMES 
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RASTERIZER_STATUS 


Members 


See Also 


RECT 


typedef struct tagRASTERIZER_ STATUS { /* rs */ 
int nSize; 
int wFlags; 

? int nLanguagelD; 

} RASTERIZER_STATUS; 


The RASTERIZER_STATUS structure contains information about whether 
TrueType is installed. This structure is filled when an application calls the 


_ GetRasterizerCaps function. 


nSize 
Specifies the size, in bytes, of the RASTERIZER_STATUS structure. 
wFlags 
Specifies whether at least one TrueType font is installed and whether TrueType 
is enabled. This value is TT_AVAILABLE and/or TT_ENABLED if TrueType 
is on the system. 


nLanguageID 
Specifies the language in the system’s SETUP.INF file. For more information 
about Microsoft language identifiers, see the StringTable structure. 


GetRasterizerCaps 


typedef struct tagRECT { /* rc */ 
int left; | 
int top; 
int right; 
int bottom; 
} RECT; 


The RECT structure defines the coordinates of the upper-left and lower-right 


corners of a rectangle. 


Members 


Comments 


RGBQUAD 


Members 
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left | 
Specifies the x-coordinate of the upper-left corner of a rectangle. 


top — 

Specifies the y-coordinate of the upper-left corner of a rectangle. 
right | 

Specifies the x-coordinate of the lower-right corner of a rectangle. 


bottom 


Sia the y-coordinate of the lower-right corner ofa rectangle. 


The width of the rectangle defined by the RECT structure must not exceed 32,767 


units. 


‘When the RECT structure is passed to the FillRect function, graphics device inter- 
face (GDI) fills the rectangle up to, but not including, the right column and bottom 


row of pixels. 


typedef struct tagRGBQUAD { /* rgbq */ 
BYTE rgbBlue; 
BYTE rgbGreen; 
BYTE rgbRed; 
BYTE rgbReserved; 
} RGBQUAD; 


The RGBQUAD structure describes a color consisting of relative intensities of 
red, green, and blue. The bmiColors member of the BITMAPINFO s structure con- 
sists of an array of RGBQUAD structures. 


— rgbBlue 


Specifies the intensity of blue in the color. 


rgbGreen 
Specifies the intensity. of green in the color. 


- rgbRed — 


Specifies the intensity of red in the color. 


rgbReserved 


Not used; must be set to zero. 
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RGBTRIPLE 


Members 


SEGINFO 


Members 


typedef struct tagRGBTRIPLE { /* rgbt */ 
BYTE rgbtBlue; 
BYTE rgbtGreen; 
BYTE rgbtRed; 

} RGBTRIPLE; 


The RGBTRIPLE structure describes a color consisting of relative intensities of 
red, green, and blue. The bmciColors member of the BITMAPCOREINFO struc- 
ture consists of an array of RGBTRIPLE structures. 


Windows applications should use the BITMAPINFO structure instead of 
BITMAPCOREINFO whenever possible. The BITMAPINFO structure uses 
an RGBQUAD structure instead of the RGBTRIPLE structure. 


rgbtBlue 
Specifies the intensity of blue in the color. 


rgbtGreen 
Specifies the intensity of green in the color. 


rgbtRed 
Specifies the intensity of red in the color. 


typedef struct tagSEGINFO { 
UINT 


offSegment; 
UINT cbSegment; 
UINT flags; 
UINT cbAlloc; 
HGLOBAL h; 


UINT alignShift; 
UINT reserved[2]; 
} SEGINFO; 


The SEGINFO structure contains information about a data or code eeereN, This 


structure is filled in by the GetCodelInfo function. 


offSegment 
Specifies the offset, in sectors, to the contents of the segment data, relative to 
the beginning of the file. (Zero means no file data is available.) The size of the 
sector is determined by shifting left by 1 the value given in the alignShift 
member. 


See Also 
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cbSegment 
Specifies the length of the segment in the file, in ae Zero means 64K. 


flags 
Contains flags which specify attributes of i segment. The following list de- 
scribes these flags: 


Bit Meaning | 

0-2 Specifies the segment type. If bit 0 is set to 1, the segment is a data seg- 
ment. Otherwise, the segment is a code segment. 

3 Specifies whether segment data is iterated. When this bit is set to 1, the 
segment data is iterated. 

4 Specifies whether the segment is movable or fixed. When this bit is set to © 
1, the segment is movable. Otherwise, it is fixed. 

5-6 Reserved. | 

7 Specifies whether the segment is a read-only data segment or an execute- 


only code segment. If this bit is set to 1 and the segment is a code seg- 
ment, the segment is an execute-only segment. If this bit is set to zero and 
the segment is a data segment, it is a read-only segment. 

Bor. Specifies whether the segment has associated relocation information. If 

this bit is set to 1, the segment has relocation information. Otherwise, the 

segment does not have relocation information. 

9 _ Specifies whether the segment has debugging information. If this bit is 
set to 1, the segment has debugging information. Otherwise, the segment 
does not have debugging information. ) 


10-15 Reserved. 


cbAlioc 
Specifies the total amount of memory allocated for the segment. This amount 
may exceed the actual size of the segment. Zero means 64K. 


h | 
Identifies the global memory for the segment. 


alignShift 
Specifies the size of the addressable sector as an exponent of 2. An executable 
_ file pads the application’s code, data, and resource segments with zero bytes so 
that the segments are always a multiple of the file-segment size. Windows dis- 
cards the extra bytes when it loads the segments from the file. 


reserved 
Specifies two reserved UINT values. 


GetCodelnfo 
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SIZE 


Members 


See Also 


So TACKTRACEENTRY 


typedef struct tagSIZE { 
int cx; 
int cy; 

} SIZE: 


The SIZE structure contains viewport extents, window extents, text extents, bit- 
map dimensions, and the aspect-ratio filter for some extended functions for Win- 
dows 3.1. 


cx 
Specifies the x-extent when a function returns. 


cy 
Specifies the y-extent when a function returns. 


GetAspectRatioFilterEx, GetBitmapDimensionEx, GetTextExtentPoint, 
Get ViewportExtEx, GetWindowExtEx, ScaleViewportExtEx, 
ScaleWindowExtEx, SetBitmapDimensionEx, Set ViewportExtEx, 
SetWindowExtEx 


#include <toolhelp.h> 


typedef struct tagSTACKTRACEENTRY { /* ste */ 
DWORD dwSize; 
HTASK hTask; 


WORD wSS; 
WORD wBP; 
WORD wCS; 
WORD wIP; 


HMODULE hModule; 

_ WORD wSegment; 
WORD wFlags; 
} STACKTRACEENTRY; 


The STACKTRACEENTRY structure contains information about one stack 
frame. This information enables an application to trace back through the stack of a 
specific task. 


} 
} 


Members 


See Also 
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dwSize 
Specifies the size of the STACKTRACEENTRY structure, in bytes. 


hTask 
Identifies the task handle for the stack. 


wss 
Contains the value in ‘the SS register. This value is used with the value of the 
wBP member to determine the next entry in the stack-trace table. 


wBP 
Contains the value in the BP register. This value is used with the wSS value to 
determine the next entry in the stack-trace table. 


wCS | 
Contains the value in the CS euiiek on return. This value is used with the 
value of the wIP member to determine the return value of the function. 


wIP 
Contains the value in the IP register on return. This value is used with the wCS 
value to determine the return value of the function. 


hModule 
Identifies the module that contains the currently executing function. 


wSegment 
Contains the segment number of the current selector. 
wFlags 
Indicates the frame ype! This type can be one of the following values: 
Value ~ Meaning 
FRAME_FAR. The CS register contains a valid code segment. 


FRAME_NEAR The CS register is null. 


StackTraceCSIPFirst, StackTraceNext, StackTraceFirst 
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SYSHEAPINFO — ra] 


fHinclude <toolhelp.h> 


typedef struct tagSYSHEAPINFO { /* shi */ 
DWORD dwSize; 
WORD wUserFreePercent; 
WORD wGDIFreePercent; . 
HGLOBAL hUserSegment; 
HGLOBAL hGDISegment; 
} SYSHEAPINFO; 


The SYSHEAPINEO structure contains information about the USER and GDI 
modules. 


Members dwSize 
Specifies the size of the SYSHEAPINFO structure, in bytes. 


wUserFreePercent 
Specifies the percentage of the USER local heap that is free. 


wGDIFreePercent | 
Specifies the percentage of the GDI local heap that is free. 


hUserSegment 
Identifies the DGROUP segment of the USER local heap. 


hGDISegment 
Identifies the DGROUP segment of the GDI local heap. 


See Also | SystemHeapInfo 


TASKENTRY 


Members 
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fFinclude <toolhelp.h> 


typedef struct tagTASKENTRY { /* te */ 


DWORD dwSize; 
HTASK hTask; 
HTASK hTaskParent; 


HINSTANCE hInst; 
HMODULE hModule; 


WORD wSS; 
WORD | wSP; 
WORD wStackTop; | 
WORD wStackMinimum; 
WORD wStackBottom; 
WORD. wcEvents; 
HGLOBAL  hQueue; 
char szModuleLMAX_MODULE_NAME + 1]; 
WORD wPSPOffset; 


HANDLE hNext; 
} TASKENTRY; 


The TASKENTRY structure contains information about one task. 


dwSize 
Specifies the size > of the TASKENTRY structure, in bytes. 


hTask 
Identifies the task handle for the stack. 


hTaskParent 
Identifies the parent of the task. 


hInst 
Identifies the instance handle of the task. This value is equivalent to the task’s 
DGROUP segment selector. 


hModule 
Identifies the module that contains the currently executing function. 


wssS 


Contains the value in the SS register. 


wSP — 
_ Contains the value in the SP register. 


wStackTop 
Specifies the offset to the Top. of the stack lowest address on the stack). 


wStackMinimum | 
Specifies the lowest seewem number of the stack during execution of the task. 
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wstackBottom 
Specifies the offset to the bottom of the stack (highest address on the stack). 


wcEvents 
Specifies the number of pending events. 


hQueue 
Identifies the task queue. 


szModule | 
Specifies the name of the module that contains the currently executing function. 


wPSPOffset 
Specifies the offset from the program segment prefix (PSP) to the beginning of 
the executable code segment. 


hNext | 
Identifies the next entry in the task list. This member is reserved for internal use 
by Windows. | 


See Also TaskFindHandle, TaskFirst, TaskNext 
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typedef struct tagTEXTMETRIC { /* tm */ 
int tmHeight; 
int tmAscent; 
int tmDescent; 
int tmInternalLeading; 
int tmExternalLeading; 
int tmAveCharWidth; 
int tmMaxCharWidth; 
int tmWeight; 
BYTE tmItalic; 
BYTE tmUnderlined; 
BYTE tmStruckOut; 
BYTE tmFirstChar; 
BYTE tmLastChar; 
BYTE tmDefaultChar; 
BYTE tmBreakChar; 
BYTE tmPitchAndFamily; 
BYTE tmCharSet; 
int tmOverhang; 
int tmDigitizedAspectx; 
int tmDigitizedAspectyY; 
} TEXTMETRIC; 


Members 
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The TEXTMETRIC structure contains basic information about a physical font. 
For Windows version 3.1, the EnumFonts and EnumFontFamilies functions 
return information about TrueType fonts ina NEWTEXTMETRIC structure. 


tmHeight 
Specifies the height of character cells. (The height is the sum of the tmAscent 
and tmDescent members.) 


tmAscent 
Specifies the ascent of character cells. (The ascent is the space between the base 
line and the top of the character cell.) 


tmDescent 
Specifies the descent of character cells. (The descent is the space between the 
bottom of the character cell and the base line.) 


tmInternalLeading 
Specifies the difference between the point size of a font and the physical 
size of the font. For TrueType fonts, this value is equal to tmHeight minus 
(s * ntmSizeEM), where s is the scaling factor for the TrueType font and 
ntmSizeEM is a value from the NEWTEXTMETRIC structure. For bitmap 
fonts, this value is used to determine the point size of a font. When an applica- 
tion specifies a negative value in the IfHeight member of the LOGFONT struc- | 
ture, the application is requesting a font whose height equals tmHeight minus 
tmInternalLeading. 


tmExternalLeading 
Specifies the amount of extra leading (space) that the application adds between 
rows. Since this area is outside the character cell, it contains no marks and will 
not be altered by text output calls in either opaque or transparent mode. The 
font designer sometimes sets this member to zero. 


tmAveChar Width 
Specifies the average width of characters in the font. For ANSI _CHARSET 
fonts, this is a weighted average of the characters “a” through “z” and the space 
character. For other character sets, this value is an unweighted average of all 
characters in the font. 


tmMaxCharWidth | | 
Specifies the “B” spacing of the widest character in the font. For more informa- 
tion about “B” spacing, see the description of the ABC structure. 


tmWeight 
Specifies the weight of the font. This member can be one of the following 
values: | 


Constant Value 
FW_DONTCARE | 0 
FW_THIN 100 


FW_EXTRALIGHT 200 
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Constant Value 
FW_ULTRALIGHT — 200 
FW_LIGHT - 300 — 
~FW_NORMAL 400 
FW_REGULAR 400 
FW_MEDIUM 500 
FW_SEMIBOLD 600 
FW_DEMIBOLD 600 
FW_BOLD | 700 : 


FW_EXTRABOLD 800 
FW_ULTRABOLD 800 


FW_BLACK 900 

FW_HEAVY 900 
tmltalic 

Specifies an italic font if it is nonzero. 
tmUnderlined | 

Specifies an underlined font if it is nonzero. 
tmStruckOut 

Specifies a “struckout” font if it is nonzero. 
tmFirstChar e.. 

Specifies the value of the first character defined in the font. 
tmLastChar 

Specifies the value of the last character defined in the font. 
tmDefaultChar | 


Specifies the value of the character that will be substituted for characters that 
are not in the font. 


tmBreakChar 
Specifies the value of the character that will be used to define word breaks for 
text justification. | 

tmPitchAndFamily 
Specifies the pitch and family of the selected font. 


The four low-order bits identify the type of font, as shown in the following list: 


Value Meaning _ 
TMPF_PITCH Designates a fixed-pitch font. 
TMPF_VECTOR Designates a vector or TrueType font. 


TMPF_TRUETYPE Designates a TrueType font. 
TMPF_DEVICE Designates a device font. 
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Some fonts are identified by several of these bits—for example, the bits 
TMPF_PITCH, TMPF_VECTOR, and TMPF_TRUETYPE would be set for 
the monospace TrueType font, Courier New. The TMPF_DEVICE bit could be 
set for a TrueType font as well, because this bit is set for both downloaded and 
device-resident fonts. 


When the TMPF_TRUETYPE bit is set, the font is usable on all output devices. 
For example, if a TrueType font existed on a printer but could not be used on 
the display, the TMPF_TRUETYPE bit would not be set for that font. 


The four high-order bits of this member designate the font family. The 

— tmPitchAndFamily member can be combined with the value OxFO by using 
the bitwise AND operator and can then be compared with the font family 
names for an identical match. The following font families are defined: 


Value Meaning 

FF_DECORATIVE Novelty fonts. Old English is an example. 

FF_DONTCARE Don’t care or don’t know. 

FF_MODERN Fonts with constant stroke width, with or without serifs. 
Pica, Elite, and Courier New are examples. 

FF_ ROMAN | Fonts with variable stroke width and with serifs. Times 
New Roman and New Century Schoolbook are examples. 

FF_SCRIPT Fonts designed to look like handwriting. Script and Cursive 
are examples. 

FF_SWISS | Fonts with variable stroke width and without serifs. MS 


Sans Serif is an example. 


tmCharSet | 


Specifies the character set of the font. The following values are defined: 
Constant Value 

ANSI_CHARSET 0 

DEFAULT_CHARSET 1 

SYMBOL_CHARSET 2 

SHIFTJIS_CHARSET 128 

OEM_CHARSET 255 

tmOverhang | 


Specifies the extra width that is added to some synthesized fonts. When synthe- 
sizing some attributes, such as bold or italic, GDI or a device sometimes adds 
width to a string on both a per-character and per-string basis. For example, GDI 
makes a string bold by expanding the intracharacter spacing and overstriking by 
an offset value and italicizes a font by skewing the string. In either case, the 
string is wider after the attribute is synthesized. For bold strings, the overhang 
is the distance by which the overstrike is offset. For italic strings, the overhang 
is the amount the top of the font is skewed past the bottom of the font. 
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Comments 


See Also 


TIMERINFO 


Members 


Comments | 


See Also 


The tmOverhang member is zero for many italic and bold TrueType fonts be- 
cause many TrueType fonts include italic and bold faces that are not synthe- 
sized. For example, the overhang for Courier New Italic is zero. 


An application that uses raster fonts can use the overhang value to determine 
the spacing between words that have different attributes. 


tmDigitizedAspectX 
Specifies the horizontal aspect of the device for which the font was designed. 


tmDigitizedAspectY 
Specifies the vertical aspect of the device for which the font was designed. The 
ratio of the tmDigitizedAspectX and tmDigitizedAspectY members is the 
aspect ratio of the device for which the font was designed. 


All sizes are given in logical units; that is, they depend on the current mapping 
mode of the display context. , 


EnumFontFamilies, EnumFonts, GetDeviceCaps, GetTextMetrics 


#include <toolhelp.h> 


typedef struct tagTIMERINFO { /* ti */ 
DWORD dwSize; 
DWORD dwmsSinceStart; 
DWORD dwmsThisVM; 

} TIMERINFO; 


The TIMERINFO structure contains the elapsed time since the current task be- 
came active and since the virtual machine (VM) started. 


dwSize — 
Specifies the size of the TIMERINFO structure, in he 


. dwmsSinceStart 


Contains the amount of time, in milliseconds, since the current task became 
active. 


dwmsThisVM 
Contains the amount of time, in milliseconds, since the current VM started. 


Tn standard mode, the dwmsSinceStart and dwmsThisVM values are the same. 


| TimerCount 
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TTPOLYCURVE a EKA 


typedef struct tagTTPOLYCURVE { 
UINT wlype; 
UINT cpfx; 
POINTFX apfx{1]; 

} TTPOLYCURVE; 


The TTPOLYCURVE structure contains information about a curve in the outline 
of a TrueT ype character. 


Members wType 
Specifies the — of curve described by the structure. This member can be one 
of the following values: 


Value Meaning 


TT_PRIM_LINE Curve is a polyline. 
TT_PRIM_QSPLINE Curve is a quadratic spline. 


cpfx 
Specifies the number of POINTFX< structures in the array. 


apfx 
Specifies an array of POINTFX structures that define the polyline or quadratic 
spline. 


Comments When an application calls the GetGlyphOutline function, a glyph outline for a 
| TrueType character is returned in a TTPOLYGONHEADER structure followed 

by as many TTPOLYCURVE structures as are required to describe the glyph. 
All points are returned as POINTF*X< structures and represent absolute positions, 
not relative moves. The starting point given by the pfxStart member of the 
TTPOLYGONHEADER structure is the point at which the outline for a contour 
begins. The TTPOLYCURVE structures that follow can be either polyline 
records or spline records. 


Polyline records are a series of points; lines drawn between the points describe the _ 
outline of the character. Spline records represent the quadratic curves used by 
TrueType (that is, quadratic b-splines). 


See Also POINTFX, TTPOLYGONHEADER 
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TTPOLYGONHEADER 


Members 


Comments 


‘See Also 


typedef struct tagTTPOLYGONHEADER { 
DWORD cb; 
DWORD dwlype; 
POINTFX pfxStart; 

} TTPOLYGONHEADER; 


The TTPOLYGONHEADER structure specifies the starting position and type of 
a contour in a TrueType character outline. 


cb 
Specifies the number of bytes required by the TTPOLYGONHEADER struc- 
ture and TTPOLYCURVE structure or structures required to describe the con- 
tour. 


dwType 
Specifies the type of character outline that is returned. Currently, this value 
must be TT_POLYGON_TYPE. 


pfxStart 
Specifies the starting point of the contour in the character outline. 


Each TTPOLYGONHEADER structure is followed by one or more TTPOLY- 
CURVE structures. 


POINTFX, TTPOLYCURVE 
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VS_FIXEDFILEINFO [34 | 


Members 


dtinclude <ver.h> 


typedef struct tagVS_FIXEDFILEINFO { /* vsffi */ 
DWORD dwSignature; 
DWORD dwStrucVersion; 
DWORD dwFileVersionMS; 
DWORD dwFileVersionLs; | 
DWORD dwProductVersionMS; 
DWORD dwProductVersionLS; 
DWORD dwFileFlagsMask; 
DWORD dwFileFlags; 
DWORD dwFile0S; 
DWORD dwFileType; 
-DWORD dwFileSubtype; 
DWORD dwFileDateMS; 
DWORD dwFileDateLS; 

} VS_FIXEDFILEINFO; 


The VS_FIXEDFILEINFO structure contains version information about a file. 


- dwSignature 


Specifies the value OxFEEFO4BD. 


dwStrucVersion 
Specifies the binary version number of this structure. The high-order word con- 
tains the major version number, and the low-order word contains the minor ver- 
sion number. This value must be greater than Ox00000029. 


~ dwFileVersionMS 


Specifies the high-order 32 bits of the binary version number for the file. The 
value of this member is used with the value of the dwFileVersionLS member 
to form a 64-bit version number. 


dwFileVersionLS 


Specifies the low-order 32 bits of the binary version number for the file. The 
value of this member is used with the dwFileVersionMS value to form a 64-bit 
version number. 


dwProductVersionMS | | 
Specifies the high-order 32 bits of the binary version number of the product 
with which the file is distributed. The value of this member is used with the 
value of the dwProductVersionLS member to form a 64-bit version number. 


dwProductVersionLS 
Specifies the low-order 32 bits of the binary version number of the product 
with which the file is distributed. The value of this member is used with the 
_ dwProductVersionMS value to form a 64-bit version number. 
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dwFileFlagsMask 


Specifies which bits in the dwFileFlags member are valid. If a bit i is set, the 
corresponding bit in the dwFileFlags member is valid. 


dwFileFlags 


Specifies the Boolean attributes of the file. The attributes can be a combination 


of the following values: 
Value 
VS_FF_DEBUG 


VS_FF_INFOINFERRED 


VS_FF_PATCHED 


VS_FF_PRERELEASE 


VS_FF_PRIVATEBUILD 


VS_FF_SPECIALBUILD 


dwFileOS 


Meaning 


File contains debugging information or is compiled 
with debugging features enabled. 


File contains a dynamically created version-informa- 
tion resource. Some of the blocks for the resource 
may be empty or incorrect. This value is not intended 
to be used in version-information resources created 
by using the VERSIONINFO statement. 


File has been modified and is not identical to the 
original shipping file of the same version number. 


File is a development version, not a commercially re- 
leased product. 


File was not built using standard release procedures. 
If this value is given, the StringFileInfo block must 
contain a PrivateBuild string. 


File was built by the original company using stan- 
dard release procedures but is a variation of the 
standard file of the same version number. If this 
value is given, the StringFileInfo block must con- 
tain a SpecialBuild string. 


Specifies the operating system for which this file was designed. This member 
can be one of the following values: 


Value 
VOS_UNKNOWN 


VOS_DOS 
VOS_NT 
VOS_WINDOWS 16 


VOS_WINDOWS32 


VOS_DOS_WINDOWS16 


VOS_DOS_WINDOWS32 


~ VOS_NT_WINDOWS32 


Meaning 

Operating system for which the file was designed is 
unknown to Windows. 

File was designed for MS-DOS. 

File was designed for Windows NT. 

File was designed for Windows version 3.0 or later. 
File was designed for 32-bit Windows. 


File was designed for Windows version 3.0 or later 
running with MS-DOS. 

File was designed for 32-bit Windows running with 
MS-DOS. 


File was designed for 32-bit Windows running with 
Windows NT. 
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The es 0x00002L, 0x00003L, Ox20000L and 0x30000L are reserved. 


dwFileType 
Specifies the general type of file. This type can be one of the following values: 


Value | | Meaning | | 

VFT_UNKNOWN File type is unknown to Windows. 

VFT_APP File contains an application. 

VFT_DLL File contains a dynamic-link library (DLL). | 
VFT_DRV File contains a device driver. If the dwFileType member is 


VFT_DRY, the dwFileSubtype member contains a more 
specific description of the driver. 


VFT_FONT File contains a font. If the dwFileType member is 
VEFT_FONT, the dwFileSubtype member contains a more 
specific description of the font. 


VFT_VXD File contains a virtual device. 
VFT_STATIC_ LIB File contains a static-link library. 


All other values are reserved for use by Microsoft. 


dwFileSubtype 
Specifies the function of the file. This member i is zero unless the dwFileType 
member is VFT_DRV, VFT_FONT, or VFT_VXD. 


If dwFileType is VFT_ DRV, dwFileSubtype may be one of the following” 
values: 


Value | Meaning 
VFT2_UNKNOWN Driver type is unknown to Windows. 
VFT2_DRV_COMM File contains a communications driver. 
VET2_DRV_PRINTER File contains a printer driver. 
VFT2_DRV_ KEYBOARD File contains a keyboard driver. 
VFT2_DRV_LANGUAGE File contains a language driver. 

~ VFT2_DRV_DISPLAY File contains a display driver. 
VFT2_DRV_MOUSE File contains a mouse driver. 
VFT2_DRV_NETWORK _ File contains a network driver. 

_VFT2_DRV_SYSTEM File contains a system driver. 


~ VFT2_DRV_INSTALLABLE File contains an installable driver. 
VFT2_DRV_SOUND File contains a sound driver. 
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Comments 


See Also 


If dwFileType is VFT_FONT, dwFileSubtype may be one of the following 


values: 

Value Meaning 

VFT2_UNKNOWN Font type is unknown to Windows. 
VFT2_FONT_RASTER File contains a raster font. 
VFT2_FONT_VECTOR File contains a vector font. 


VFT2_FONT_TRUETYPE File contains a TrueType font. 


If dwFileType is VFT_VXD, dwFileSubtype contains the virtual-device iden- 
tifier included in the virtual-device control block. 


All dwFileSubtype values not listed here are reserved for use by Microsoft. 


dwFileDateMS 
Specifies the high-order 32 bits of a binary date/time stamp for the file. The 
value of this member is used with the value of the dwFileDateLS member to 
form a 64-bit number representing the date and time the file was created. 


dwFileDateLS 
Specifies the low-order 32 bits of a binary date/time stamp for the file. The 
value of this member is used with the dwFileDateMS value to form a 64-bit 
number representing the date and time the file was created. 


The binary version numbers specified in this structure are intended to be integers 
rather than character strings. For a file or product that has decimal points or letters 
in its version number, the corresponding binary version number should be a 
reasonable numeric representation. 


A third-party developer can use the file-version values to reflect a private version- 


numbering scheme, as long as each new version of the product has a higher num- 
ber than the previous version. The File Installation library functions use these 
values when comparing the ages of files. 


Microsoft Windows Resource Compiler sets the dwFileDateMS and 
dwFileDateLS members to zero. 


VerQuery Value 


WINDEBUGINFO 


typedef struct tagWINDEBUGINFO { 


Members | 


UINT 
DWORD 
DWORD 
char 
DWORD 
DWORD 
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flags; 

dwOptions; 
dwFilter; 
achAllocModule[8]; 
dwAllocBreak; 
dwAllocCount; 


} WINDEBUGINFO; 


The WINDEBUGINFO structure contains current Syn denvePe information 
for the debugging version of Windows 3.1. 


flags 


Specifies which members of the WINDEBUGINFO structure are valid. This 
member can be one or more of the following values: 


Value | Meaning | 
WDI_OPTIONS dwOptions member is valid. 
WDI_FILTER | dwFilter member is valid. 


WD ALLOCBREAK _ achAllocModule, dwAllocBreak, and dwAllocCount 


dwOptions 


members are valid. 


Specifies debugging options. This member is valid only if WDI_OPTIONS is 
specified in the flags member. It can be one or more of the following values: 


Value Meaning 


Constant 
DBO_CHECKHEAP 0x0001 Performs local heap checking after 
| all calls to functions that manipu- 
late local memory. 


DBO_BUFFERFILL 0x0004 Fills buffers passed to API func- 


tions with OxF9. This ensures that 

the supplied buffer is completely 
writable and helps detect overwrite 
problems when the supplied buffer | 
size is not large enough. 


DBO_DISABLEGPTRAPPING 0x0010 Disables hooking of the fault inter- 


rupt vectors. This option is not 
typically used by application 
developers, because parameter 
validation can cause many spurious 
traps that are not errors. 
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Constant 
DBO_CHECKFREE 


DBO_INT3BREAK 


DBO_NOFATALBREAK 


DBO_NOERRORBREAK 


DBO_WARNINGBREAK 


DBO_TRACEBREAK 


DBO_SILENT 


-dwFilter 


Value 
0x0020 


0x0100 


0x0400 


0x0800 


0x 1000 


0x2000 


0x8000 


Meaning 


_ Fills all freed local memory with 


OxFB. All newly allocated memory 
is checked to ensure that it is still 
filled with OxFB—this ensures that 
no application has written into a 
freed memory object. This 

option has no effect if 
DBO_CHECKHEAP is not 
specified. 

Breaks to the debugger with simple 
INT 3 rather than a call to the 
FatalExit function. This option 
does not generate a stack backtrace. 


Does not break with the “abort, 
break, ignore” prompt if a 
DBF_FATAL message occurs. 
Does not break with the “abort, 
break, ignore” prompt if a 
DBF_ERROR message occurs. 
This option also applies to invalid 
parameter errors. 


Breaks with the “abort, break, ig- 
nore” prompt if a 
DBF_WARNING 

message occurs. (Normally, 
DBF_WARNING messages are 
displayed but no break occurs). 
This option also applies to invalid 
parameter warnings. 


Breaks with the “abort, break, 
ignore” on any DBF_TRACE 
message that matches the value 
specified in the dwFilter member. 


Does not display warning, error, or 
fatal messages except in cases 
where a stack trace and “abort, 
break, ignore” prompt would occur. 


Specifies filtering options for DBF_TRACE messages. (Normally, trace mes-_ 
sages are not sent to the debug terminal.) This member can be one or more of 


the following values: 


Comments . | 
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Constant 3 Value Meaning 
DBF_KRN_MEMMAN 0x0001 Enables KERNEL messages related 
| to local and global memory manage- 
ment. 


DBF_KRN_LOADMODULE 0x0002 Enables KERNEL messages related 
to module loading. 


DBF_KRN. SEGMENTLOAD 0x0004 Enables KERNEL messages related 
to segment loading. 


DBF_APPLICATION 0x0008 Enables trace messages originating 
| from an application. 

DBF_DRIVER 0x0010 Enables trace messages originating 
from device drivers. 

DBF_PENWIN 0x0020 Enables trace nese originating 
from PENWIN. | 

DBF_MMSYSTEM 0x0040 Enables trace messages originating 
from MMSYSTEM. | 

DBF_GDI ) 0x0400 Enables trace messages originating 
from GDI. 

DBF_USER 0x0800 Enables trace messages originating © 
from USER. 

DBF_KERNEL 0x1000 Enables any trace message originat- 


ing from KERNEL. (This is a combi- 
nation of DBF_KRN_ MEMMAN, 
DBF_KRN_LOADMODULE, and 
DBF_KRN_SEGMENTLOAD.) 


achAllocModule 
Specifies the name of the application module. (This can be different from the 
name of the executable file.) This cannot be the name of a dynamic-link library 
(DLL). The name is limited to 8 characters. 


dwAllocBreak 


Specifies the number of global or local memory aecations to allow before fail- 
ing allocation requests. When the count of allocations reaches the number 
_ specified in this member, that allocation and all subsequent allocations fail. If 
this member is zero, no allocation break is set, but the system counts allocations 
_ and reports the current count in the dwAllocCount member. 


dwAllocCount 
Current count of allocations. (This information is typically retrieved by calling 


~~ the GetWinDebuginfo function.) 


Tbevelopin can use the achAllocModule, dwAllocBreak, and dwAllocCount 
members to ensure that an application performs correctly in out-of-memory condi- 
tions. Because memory allocations made by the system fail once the break count is 
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reached, calls to functions such as CreateWindow, CreateBrush, and Select- 
Object will fail as well. Only allocations made within the context of the applica- 
tion specified by the achAllocModule member are affected by the allocation 
break count. 


See Also DebugOutput, GetWinDebugInfo, SetWinDebugInfo 


WINDOWPLACEMENT aa 


typedef struct tagWINDOWPLACEMENT { /* wndpl */ 
UINT length; 
UINT flags; 


UINT showCmd; 

POINT ptMinPosition; 

POINT ptMaxPosition; 

RECT rcNormal Position; 
} WINDOWPLACEMENT; 


The WINDOWPLACEMENT structure contains information about the place- 
ment of a window on the screen. 


Members length 
Specifies the length, in bytes, of the structure. (The GetWindowPlacement 
function returns an error if this member is not specified correctly.) 
flags 
Specifies flags that control the position of the minimized window and the 
method by which the window is restored. This member can be one or both of 


the following flags: 
Value | Meaning 
WPF_SETMINPOSITION Specifies that the x- and y-positions of the 


minimized window may be specified. This 
flag must be specified if the coordinates are 
set in the ptMinPosition member. 


WPF_RESTORETOMAXIMIZED __ Specifies that the restored window will be 
maximized, regardless of whether it was _ 

maximized before it was minimized. This 
setting is valid only the next time the win- 
dow is restored. It does not change the de- 
fault restoration behavior. This flag is valid _ 
only when the SW_SHOWMINIMIZED 
value is specified for the showCmd member. 


‘See Also. 


showCmd 
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Specifies the current show state of the window. This member may be one of the 


following values: 
Value 
SW_HIDE 


SW_MINIMIZE 


SW_RESTORE 


SW_SHOW 
SW_SHOWMAXIMIZED 


SW_SHOWMINIMIZED 
SW_SHOWMINNOACTIVE 


SW_SHOWNA 


SW_SHOWNOACTIVATE 


SW_SHOWNORMAL 


ptMinPosition 


Meaning 


Hides the window and passes activation to 
another window. | 


Minimizes the specified window and activates the 
top-level window in the system’s list. 


Activates and displays a window. If the window 
is minimized or maximized, Windows restores it 
to its original size and position (same as 
SW_SHOWNORMAL). 


Activates a window and displays it in its current 
size and position. 


Activates a window and displays it as a maxi- 
mized window. 


Activates a window and displays it as an icon. 


Displays a window as an icon. The window that is 
currently active remains active. 


Displays a window in its current state. The win- 
dow that is currently active remains active. 


Displays a window in its most recent size and 
position. The window that is currently active re- 
mains active. 


Activates and displays a window. If the window 
is minimized or maximized, Windows restores it 
to its original size and position (same as 
SW_RESTORE). 


Specifies the position of the window’s top-left corner when the window i is min- 


imized. 


ptMaxPosition 


Specifies the position of the window Ss top- -left corner when the window is maxi- 


mized. 
rcNormalPosition 


Specifies the window’s coordinates when the window is in the normal 


(restored) position. 


POINT, RECT, ShowWindow 
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WINDOWPOS aa] 


typedef struct tagWINDOWPOS { /* wp */ 


HWND hwnd; 

HWND hwndInsertAfter; 
int x: 

int ys 

int CX; 

int Cy; 

UINT flags; 


} WINDOWPOS; 


The WINDOWPOS structure contains information about the size and position of 
a window. 


Members hwnd 
Identifies the window. 


hwndInsertAfter 
Identifies the window behind which this window is placed. 


x | 
Specifies the position of the left edge of the window. 


Specifies the position of the right edge of the window. © 


Cx 
Specifies the window width. 
cy 
Specifies the window height. 
flags 
Specifies window-positioning options. This member can be one of the follow- 
ing values: 
Value Meaning 
SWP_DRAWFRAME Draws a frame (defined in the class description for 
the window) around the window. The window re- 
ceives a WM_NCCALCSIZE message. 
SWP_HIDEWINDOW Hides the window. 
SWP_NOACTIVATE Does not activate the window. 
SWP_NOMOVE | Retains current position (ignores the x and y mem- 
bers). 
SWP_NOOWNERZORDER Does not change the owner window’s position in 
| the Z order. | 
SWP_NOSIZE Retains current size (ignores the cx and cy mem- 


bers). 


See Also 


WNDCLASS 


Members 


| Value 


SWP_NOREDRAW 
SWP_NOREPOSITION 
SWP_NOZORDER 


SWP_SHOWWINDOW 


EndDeferWindowPos 


typedef struct tagWNDCLASS { 


UINT style; 
WNDPROC lpfnWndProc; 
int | cbClsExtra; 
int ~ cbWndExtra; 
HINSTANCE hInstance; 
HICON hIcon; 


HCURSOR  hCursor; 


HBRUSH —-hbrBackground; 
LPCSTR lpszMenuName; 
LPCSTR lpszClassName; 


} WNDCLASS; 
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Meaning 


_ Does not redraw changes. 


Same as SWP_NOOWNERZORDER. 


Retains current ordering (ignores the hwnd- 
InsertAfter member). 


Displays the window. 


/* wo */ 


The WNDCLASS structure contains the class attributes that are registered by the 


RegisterClass function. 


Style 


Specifies the class style. These 


styles can be combined by using the bitwise OR 


operator. This can be any combination of the following values: 


Value 


CS_BYTEALIGNCLIENT 


CS_BYTEALIGNWINDOW 


CS_CLASSDC 


CS_DBLCLKS 


Meaning 


Aligns the client area of a window on the byte 
boundary (in the x-direction). 

Aligns a window on the byte boundary (in the x- 
direction). This flag should be set by applications 
that perform bitmap operations in windows by 
using the BitBlt function. : 

Gives the window class its own display context 
(shared by instances). 


Sends double-click messages to a window. 
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Value Meaning 


CS_GLOBALCLASS Specifies that the window class is an application 
global class. An application global class is created 
by an application or library and is available to all 
applications. The class is destroyed when the ap- 
plication or library that created the class exits; it is 
essential, therefore, that all windows created with 
the application global class be closed before this 


occurs. 

CS_HREDRAW Redraws the entire window if the horizontal size 
changes. 

CS_NOCLOSE - Inhibits the close apna on the System menu. 

CS_OWNDC Gives each window instance its own display con- 


text. Note that although the CS_ OWNDC style is 
convenient, it must be used with discretion be- 
cause each display context occupies approxi- 
mately 800 bytes of memory. 


CS_PARENTDC | Gives the display context of the parent window to 
the window class. 
CS_SAVEBITS Specifies that the system should try to save the 


screen image behind a window created from this 
window class as a bitmap. Later, when the win- 
dow is removed, the system uses the bitmap to 
quickly restore the screen image. This style is use- 
ful for small windows that are displayed briefly 

_ and then removed before much other screen activ- 
ity takes place (for example, menus or dialog 
boxes). This style increases the time required to 
display the window since the system must first al- 
locate memory to store the bitmap. 


CS_ VREDRAW Redraws the entire window if the vertical size 
changes. 


_IpfnWndProc 
Points to the window procedure. For more information, see the description of 
the WindowProc callback function. 


cbClIsExtra 
Specifies the number of bytes to allocate following the window-class structure. 
These bytes are initialized to zero. 


cbWndExtra | 
Specifies the number of bytes to allocate following the window instance. These 
bytes are initialized to zero. If an application uses the WNDCLASS structure to 
register a dialog box created with the CLASS directive in the resource file, it 
must set this member to Pests a Ou Nene, 
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hInstance | 
Identifies the class module. This member must be an instance handle and must 
not be NULL. 


hIcon 

Identifies the class icon. This member must be a handle to an icon resource. If 
this member is NULL, the application must draw an icon whenever the user 
minimizes the application’s window. 


hCursor | 
Identifies the class cursor. This member must be a handle to a cursor resource. 
If this member is NULL, the application must explicitly set the cursor shape 
whenever the mouse moves into the application’s window. 


hbrBackground 
Identifies the class background brush. This member can be either a handle to 
the physical brush that is to be used for painting the background, or it can be a 
color value. If a color value is given, it must be one of the standard system 
colors listed below, and the value 1 must be added to the chosen color (for ex- 
ample, COLOR_BACKGROUND + | specifies the system background color). 
If a color value is given, it must be converted to one of the following HBRUSH 
types: | 
COLOR_ACTIVEBORDER © COLOR_HIGHLIGHTTEXT 


COLOR_ACTIVECAPTION COLOR_INACTIVEBORDER 
COLOR_APPWORKSPACE COLOR_INACTIVECAPTION 


COLOR_BACKGROUND COLOR_INACTIVECAPTIONTEXT 
COLOR_BTNFACE COLOR_MENU 
COLOR_BTNSHADOW ~ COLOR_MENUTEXT 
COLOR_BTNTEXT COLOR_SCROLLBAR 
COLOR_CAPTIONTEXT COLOR_WINDOW 
COLOR_GRAYTEXT COLOR_WINDOWFRAME 
COLOR_HIGHLIGHT COLOR_WINDOWTEXT 


The system automatically deletes class background brushes when the class is 
freed. An application should not delete these brushes, because a class may be 
cused by multiple instances of the application. 


When this member is NULL, the application must paint its own background 
whenever it is requested to paint in its client area. The application can deter- 
mine when the background needs painting by processing the message 
WM_ERASEBKGND or by testing the fErase member of the PAINT- 
STRUCT structure filled by the BeginPaint function. 
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IpszMenuName 
Points to a null-terminated string that specifies en resource name of the class 
menu (as the name appears in the resource file). If an integer is used to identify 
the menu, the MAKEINTRESOURCE macro can be used. If this member is 
NULL, windows belonging to this class have no default menu. 


IpszClassName 
Points to a null-terminated string that specifies the name of the window class. 


See Also PAINTSTRUCT 


Macros 


Alphabetic Reference 


Chapter 4 
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This chapter describes the purpose and defines the parameters of macros 
associated with functions and structures for the Microsoft Windows operating 
system, version 3.1. It lists the Windows macros in alphabetic order. 


DECLARE_HANDLE a] 


DECLARE_HANDLE(xame) 


The DECLARE_HANDLE macro creates a data type that can be used to define 
16-bit handles. 


Parameters name 
Specifies the name of the new data type. 


Comments The DECLARE_HANDLE macro is defined in WINDOWS.H as follows: 


#tdefine DECLARE_HANDLE(name) struct names { int unused; }; \ 
typedef const struct namedHt_ NEAR* name 


See Also DECLARE_HANDLE32 


DECLARE_HANDLE32 ne be ee 


#include <ddeml.h> 
DECLARE_ HANDLE32(name) 


The DECLARE_HANDLE32 macro creates a data type that can be used to de- 
fine 32-bit handles. 


Parameters =# name 
Specifies the name of the new data type. 
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Comments The DECLARE_HANDLE32 macro is defined in DDEML.H as follows: 
#tdefine DECLARE_HANDLE32(name) struct name#¥#.. { int unused; }; \ 
typedef const struct named _far* name 
See Also DECLARE_HANDLE 


FIELDOFFSET aa] 


int FIELDOFFSET(type, field) 


The FIELDOFFSET macro computes the address offset of the specified member 
in the structure specified by the type parameter. 


Parameters type 
| Specifies the name of the structure. 
field 
Specifies the name of the member defined within the given structure. 
Return Value The return value is the address offset of the given structure member. 
Comments The FIELDOFFSET macro is defined in WINDOWS.H as follows: 


#tdefine FIELDOFFSET(type, field) (Cint)(&( (type NEAR*)1)->field)-1) 
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GetBValue | | [3.4 | 


BYTE GetB Value(rgb) | 
DWORD rgb; /* RGB color value */ 


The GetBValue macro extracts the intensity value of the blue color field from the 
32-bit integer value specified by the rgb parameter. 


Parameters rgb 
Specifies the RGB color value. 


Return Value The return value specifies the intensity of the blue color field. 


Comments The GetBValue macro is defined in WINDOWS.H as follows: 


fidefine GetBValue(rgb) ((BYTE)((rgb)>>16)) 


See Also GetGValue, GetRValue, RGB 


GetGValue — & Ga] 


BYTE GetGValue(rgb) 
DWORD rgb; /* RGB color value ‘fi 


The GetG Value macro extracts the intensity value of the green color field from 
the 32-bit integer value specified by the rgb parameter. 


Parameters — rgb 
| | Specifies the RGB color value. 


Return Value | The return value specifies the intensity of the green color field. 


Comments | ne The GetG Value macro is defined in WINDOWS.H as follows: 


#define GetGValue(rgb) ((BYTE)(((WORD)(rgb)) >> 8)) 


~ See Also | GetBValue, GetRValue, RGB 
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GetRValue — 


BYTE GetRValue(rgb) 

DWORD rgb; /* RGB color value **/ 
The GetRValue macro extracts the intensity value of the red color field from the | 
32-bit integer value specified by the rgb parameter. 


Parameters rgb 
Specifies the RGB color value. 


Return Value The return value specifies the intensity of the red color field. 


Comments The GetR Value macro is defined in WINDOWS.H as follows: 


dtdefine GetRValue(rab) ((BYTE) (rgb) ) 


See Also GetBValue, GetG Value, RGB 


GlobalDiscard [ 2.x | 


HGLOBAL GlobalDiscard(hglb) 
HGLOBAL heglb; /* handle of object to discard a 


The GlobalDiscard macro discards the given global memory object. The lock 
count of the memory object must be zero. 


Parameters hglb 
Identifies the global memory object to be discarded. 


Return Value _ The return value is a handle of the discarded object if the macro is successful. 
Otherwise, it is NULL. 


Comments The GlobalDiscard macro discards only global objects that an application allo- 
cated with the GMEM_DISCARDABLE and GMEM_MOVEABLE flags set. 
The macro fails if an application attempts to discard a fixed or locked object. 


Although GlobalDiscard removes the global memory object from memory, the 
object’s handle remains valid. An application can subsequently pass the handle to 
the GlobalReAlloc function to allocate another global memory object identified 
by the same handle. _ | 
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The GlobalDiscard macro is defined in WINDOWS.H as follows: 


dkdefine GlobalDiscard(h) GlobalReAlloc(h, @L, GMEM_ MOVEABLE) 


See Also GlobalReAlloc 


HIBYTE er, 


BYTE HIBYTE(winteger) 
WORD winteger; /* value from which high byte is retrieved ah 


_ The HIBYTE macro retrieves the high-order byte from the integer value specified 
by the wlnteger parameter. 


Parameters wlnteger 
Specifies the value to be converted. 


Return Value The return value specifies the high-order byte of the given value. 


~ Comments The HIBYTE macro is defined in WINDOWS.H as follows: 
#tdefine HIBYTE(w) ((BYTE)(((WORD)(w) >> 8) & OxFF)) 


HIWORD EP fag 


WORD HIWORD(dwinteger) 
DWORD dwinteger; /* value from which high wend is retrieved oe, 


The HIWORD macro retrieves the high-order word from the 32-bit inte ger value 
specified by the dwlnteger parameter. : 


Parameters = = - dwinteger 
ook: Specifies the value to be converted. 


Return Value The return value specifies the high-order word of the given 32-bit integer value. 


Comments _ The HIWORD macro is defined in WINDOWS.H as follows: 
d#define HIWORD(1) ((CWORD)((((DWORD)(1)) >> 16) & OXxFFFF)) 
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LOBYTE | [ 2.x | 


BYTE LOBYTE(wVal) 
WORD wVal; /* value from which low byte is retrieved / 


The LOBYTE macro extracts the low-order byte from the short-integer value: 
specified by the wVal parameter. 


Parameters wval 
Specifies the value to be converted. 


Return Value The return value specifies the low-order byte of the value. 


Comments The LOBYTE macro is defined in WINDOWS.H as follows: 


define LOBYTE(w) ((BYTE)(w)) 


See Also LOWORD 


LocalDiscard [2.x ] 


HLOCAL LocalDiscard(hloc) 
HLOCAL hiloc; /* handle of object to discard sf 


The LocalDiscard macro discards the given local memory object. The lock count 
of the memory object must be zero. 


Parameters hloc 
Identifies the local memory object to be discarded. 


Return Value The return value is equal to the hloc parameter if the macro is successful. Other- 
wise, itis NULL. 


Comments Although the LocalDiscard macro removes the local memory object from 
memory, the object’s handle remains valid. An application can subsequently pass 
the handle to the LocalReAlloc function to allocate another local memory object 
identified by the same handle. 
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The LocalLock function increments (increases by one) a memory object’s lock 
count. The LocalUnlock function decrements (decreases by one) the lock count. 


The LocalDiscard macro is defined in WINDOWS.H as follows: 


dKdefine LocalDiscard(h) LocalReAlloc(h, @, LMEM_MOVEABLE) 


See Also LocalLock, LocalReAlloc, LocalUnlock 


LockData | [ex] 
HANDLE LockData(dummy) 


The LockData macro locks the current data segment in memory. It is intended to 
be used in modules that have movable data segments. 


Parameters. | dummy | 
| This pau is ignored. 


Return Value The return value identifies the locked data segment if the function is successful. 
Otherwise, it is NULL. 


Comments | The LockData macro is defined in WINDOWS.H as follows: 


define LockData(dummy) LockSegment((UINT)-1)_ 


See Also - LockSegment 


WORD LOWORD(dwVal) 

DWORD dwvVal; /* value from which low word is retrieved a 
The LOWORD macro extracts the low-order word from the 32- bit integer value 
specified by the dwVal parameter. 


Parameters dwVal 
| Specifies the value to be converted. 
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Return Value The return value specifies the low-order word of the 32-bit integer value. 


Comments The LOWORD macro is defined in WINDOWS.H as follows: 
define LOWORD(1) ((WORD)(DWORD)(1)) 


See Also LOBYTE 


MAKEINTATOM ra 


LPCSTR MAKEINTATOM(wInteger) 
WORD winteger; /* integer to make into atom | 


The MAKEINTATOM macro creates an integer atom that represents a character 
string of decimal digits. 


Integer atoms created by this macro can be added to the atom table using th 
AddAtom function. | 


Parameters wlnteger 
Specifies the numeric value to be made into an integer atom. 


Return Value The return value is a pointer to the atom created for the given integer. 


Comments Although the return value of the MAKEINTATOM macro is cast as an 
LPCSTR, the return value cannot be used as a string pointer, except when it is 
passed to atom-management functions that require an LPCSTR parameter. 


The DeleteAtom function always succeeds for integer atoms, even though it does 
nothing. The string returned by the GetAtomName function for an integer atom 
will be a null-terminated string where the first character is a pound sign (#) and the 
remaining characters are the word used in the MAKEINTATOM macro. 


The MAKEINTATOM macro is defined in WINDOWS.H as follows: 
#define MAKEINTATOM(7) ((LPCSTR)MAKELP(NULL, (i))) 
Example The following example uses the MAKEINTATOM macro to convert the number 


32,565 into an integer atom. The atom is then added to the local atom table by the 
AddAtom function: 


See Also 
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ATOM at; | 
char szMsg[8@]; 
LPCSTR IpszAtom; 


IpszAtom = MAKEINTATOM(32565); 
= AddAtom(1pszAtom) ; 


if (at == @) : 
MessageBox(hwnd, “AddAtom failed", "", MB_ICONSTOP); 

else { 

sprintf(szMsg, "AddAtom returned %u", at); 

MessageBox(hwnd, szMsg, "", MB_OK); 


AddAtom, DeleteAtom, GetAtomName 


MAKEINTRESOURCE bo a 


LPCSTR MAKEINTRESOURCE(idResource) 


WORD idResource; 


Parameters 
Return Value 


Comments | 


See Also 


/* resource identifier to convert */ 


The MAKEINTRESOURCE macro converts an integer resource identifier into a 
value compatible with Windows resource-management functions. This macro is 
used in place of a string containing the name of the resource. 


idResource 
Specifies the integer resource identifier to be converted. 


The return value contains the idResource ee in the low-order word aut 
zero in the high-order word. 


The MAKEINTRESOURCE macro is defined in WINDOWS.H as follows: 


#tdefine MAKEINTRESOURCE(7) ((LPCSTR)MAKELP(NULL, A) 


MAKELP 
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MAKELONG [ 2.x | 


DWORD MAKELONG(wLovw, wHigh) 
WORD wLow; /* low-order word of long value =) 
WORD wHigh; /* tigh-order word of long value | 


The MAKELONG macro creates an unsigned long integer by concatenating two 
integer values, specified by the wLow and wHigh parameters. 


Parameters wLow 
Specifies the low-order word of the new long value. 
wHigh 
Specifies the high-order word of the new long value. 
Return Value The return value specifies an unsigned long-integer value. 
Comments | The MAKELONG macro is defined in WINDOWS.H as follows: 


#tdefine MAKELONG(low, high) \ 
(CLONG)((CWORD)(low)) | (C(DWORD)((WORD)(high))) << 16))) 


MAKELP an 


void FAR* MAKELP(wSel, wOff) 
WORD wSel; /* selector * / 
WORD wOff /* offset a | 


The MAKELP macro combines a segment selector and an address offset to create 
a long (32-bit) pointer to a memory address. 


Parameters wSel 
Specifies a segment selector. 
wOff | | 
Specifies an offset from the beginning of the given segment to the desired byte. 
Return Value’ The return value is a long pointer to an unspecified data type. 
Comments The MAKELP macro is defined in WINDOWS.H as follows: 


#tdefine MAKELP(sel, off) ((void FAR*)MAKELONG( (off), (sel))) - 


See Also MAKELONG 
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MAKELPARAM [34 | 


LPARAM MAKELPARAM(wLoy, wHigh) 
WORD wLow; /* low-order word */ 
WORD whHigh; /* high-order word */ 


The MAKELPARAM macro creates an unsigned long integer for use as an 
/Param parameter in a message. The macro concatenates two integer values, 
specified by the wLow and wHigh parameters. 


Parameters wLow 
Specifies the low-order word of the new long value. 
wHigh 
Specifies the high-order word of the new long value. 
Return Value The return value specifies an unsigned long-integer value. 
Comments The MAKELPARAM macro is defined in WINDOWS.H as follows: 


#tdefine MAKELPARAM( low, high) ((LPARAM)MAKELONG( low, high) ) 


See Also MAKELONG, MAKELRESULT 


MAKELRESULT ra] 


LRESULT MAKELRESULT(wLovw, wHigh) 
WORD wLow; /* low-order word */ 
WORD wHigh; /* high-order word | 


The MAKELRESULT macro creates an unsigned long integer for use as a return 
value from a window procedure. The macro concatenates two eer values, 
specified by the wLow and eee parameters. 


Parameters wLow 
Specifies the low-order word of the new long value. 

wHigh ; 
Specifies the high-order word of the new long value. 


Return Value The return value specifies an unsigned long-integer value. 
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Comments The MAKELRESULT macro is defined in WINDOWS.H as follows: 
##define MAKELRESULT( low, high) ((LRESULT )MAKELONG(1ow, high) ) 


See Also | MAKELONG, MAKELPARAM 


MAKEPOINT Ea 


POINT MAKEPOINT(/val) | 
DWORD lval;__—_—s/* coordinates of a point af 


The MAKEPOINT macro converts a long value that contains the x- and y-coordi- _ 
nates of a point into a POINT structure. This macro is useful for converting the — 
long value returned by the GetMessagePos function into a POINT structure and 
for converting the /Param value passed with mouse messages into a POINT struc- 
ture containing the mouse coordinates. 


Parameters lval 
Specifies the coordinates of a point. The x-coordinate is in the low-order word, 
and the y-coordinate is in the high-order word. 


Return Value The return value is a pointer to a POINT structure. 
Comments The MAKEPOINT macro is defined in WIN DOWS.H as follows: 
define MAKEPOINT(1) (*((POINT FAR*)&(1))) 


The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
THU Xs 
int y; 

} POINT; 


The MAKEPOINT macro is not compatible with the Windows 32-bit eee 
programming interface (API). | 


See Also GetMessagePos 
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max _ rox] 
int max(value!, value2) 


The max macro compares two values and returns the value of the larger one. The 
data type can be any numerical data type, signed or unsigned. The type of the argu- 
ments and the return value is the same. 


Parameters value 1 
Specifies the first of two values. 


value2 
Specifies the second of two values. 


Return Value The return value is value] or value2, whichever is greater. | 


Comments The max macro is defined in WINDOWS.H as follows: 
d#tdefine max(a, b) (((a) > (b)) ? (a) : (b)) 


See Also min 


min 
int min(valuel, value2) 


The min macro compares two values and returns the value of the smaller one. The 
data type can be any numerical data type, signed or Masiene The type of the argu- 
ments and the return value is the same. 


Parameters value I 
Specifies the first of two values. 


value2 
Specifies the second of two values. 


Return Value The return value is valuel or value2, whichever is smaller. | 
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Comments The min macro is defined in WINDOWS.H as follows: 
d#tdefine min(a, b) (((a) < (b)) ? (a) : (b)) 


See Also max 


OFFSETOF a 


WORD OFFSETOF(/p) 
void FAR* /p; /* long pointer */ 


The OFFSETOF macro retrieves the address offset of the specified long pointer. 


Parameters Ip 
Specifies a long pointer. 


Return Value The return value is the offset address. 

Comments The OFFSETOF macro is defined in WINDOWS.H as follows: 
#Kdefine OFFSETOF(1p) LOWORD(1p) 

See Also LOWORD, SELECTOROF 


PALETTEINDEX 


COLORREF PALETTEINDEX(wPaletteIndex) 
WORD wPaletteIndex; /* index to palette entry | 


The PALETTEINDEX macro accepts an index to a logical-color palette entry 
and returns a value consisting of 1 in the high-order byte and the palette-entry 
index in the low-order byte. This is called a palette-entry specifier. An application 
using a color palette can pass this specifier instead of an explicit RGB value to 
functions that expect a color. This allows the function to use the color in the 
specified palette entry. 
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Parameters — wPaletteIndex 
Specifies an index to the palette entry containing the color to be used for a 
graphics operation. 
Return Value The return value is a logical-palette index specifier. When using a logical palette, 
an application can use this specifier in place of an explicit RGB value for graphics- 
device interface (GDI) functions that require a color. 


Comments The PALETTEINDEX macro is defined in WINDOWS.H as follows: 


#define PALETTEINDEX(71) ((COLORREF)(@x@1000000L | (DWORD) (WORD) (i))) 


See Also PALETTERGB, RGB 


PALETTERGB 


COLORREF PALETTERGB(cRed, cGreen, cBlue) 


BYTE cRed; _/* red component of palette-relative RGB yf 
BYTE cGreen; /* green component of palette-relative RGB _ ya 
BYTE cBlue; /* blue component of palette-relative RGB */ 


The PALETTERGB macro accepts three values representing relative intensities 
of red, green, and blue and returns a value consisting of 2 in the high-order byte 
and an RGB value in the three low-order bytes. This is called a palette-relative 
RGB specifier. An application using a color palette can pass this specifier instead 
of an explicit RGB value to functions that expect a color. 


For output devices that support logical palettes, Windows matches a palette-rela- 
tive RGB value to the nearest color in the logical palette of the device context as 
though the application had specified an index to that palette entry. If an output dev- 
ice does not support a system palette, then Windows uses the palette-relative RGB 
as though it were a conventional RGB doubleword returned by the RGB macro. 


Parameters cRed | 3 
: Specifies the intensity of the red color field. 


cGreen | 
Specifies the intensity of the green color field. 


cBlue | : 
Specifies the intensity of the blue color field. 


Return Value The return value specifies a palette-relative RGB value. _ 
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Comments 


See Also 


RGB 


The PALETTERGB macro is defined in WINDOWS.H as follows: 


d#define PALETTERGB(r,g,b) (@x@2000000L | RGB(r,g,b)) 


PALETTEINDEX, RGB 


COLORREF RGB(cRed, cGreen, cBlue) 


BYTE cRed; 


BYTE cGreen; 
BYTE cBlue; 


Parameters 


Return Value 


Comments 


Comments 


See Also 


/* red component of color sy 
/* green component of color ay 
/* blue component of color */ 


The RGB macro selects an RGB color based on the parameters supplied and the 
color capabilities of the output device. = 


cRed 
Specifies the intensity of the red color field. 


cGreen 
Specifies the intensity of the green color field. 


cBlue 
Specifies the intensity of the blue color field. 


The return value specifies the resultant RGB color. 


The intensity for each argument can range from 0 through 25 5. If all three intensi- 
ties are specified as zero, the result is black. If all three intensities are specified as 
255, the result is white. 


For information on using color values in a color palette, see the descriptions of the 
PALETTEINDEX and PALETTERGB macros earlier in this chapter. 


The RGB macro is defined in WINDOWS.H as follows: 


#tdefine RGB(r,g,b) t CEOLORR ETC CCB TIE) (ro CCMORUICO) S680) \ 
(C(DWORD) (BYTE) (b))<<16))) 


GetBValue, GetG Value, GetRValue, PALETTEINDEX, PALETTERGB 
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SELECTOROF aa] 


WORD SELECTOROKF(/p) | 
void FAR* Ip; /* long pointer a 


The SELECTOROF macro retrieves the segment selector from the specified long 
pointer. | 


Parameters lp 
Specifies a long pointer. 


Return Value The return value is the segment selector. 

Comments The SELECTOROF macro is defined in WINDOWS.H as follows: 
#tdefine SELECTOROF(1p) HIWORD(1p) 

See Also HIWORD, OFFSETOF 


‘UnlockData faa] 


HANDLE UnlockData(dummy) 


The UnlockData macro unlocks the current data segment. It is intended to be used — 
by modules that have movable data segments. 


Parameters dummy 7 
_ This parameter is ignored. 


Return Value The return value specifies the outcome of the UnlockSegment function. It is zero 
if the segment’s lock count was decreased to zero. Otherwise, the return value is 
nonzero. 


Comments The UnlockData macro is defined in WINDOWS.H as follows: 


#define UnlockData(dummy ) UnlockSegment((UINT)-1) | 


See Also LockData, UnlockSegment 
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UnlockResource 


BOOL UnlockResource(hResData) 
HGLOBAL hResData; /* handle of memory object to unlock */ 


The UnlockResource macro unlocks the resource specified by the hResData 
parameter and decreases the reference count of the resource by one. 


Parameters hResData 
Identifies the global memory object to be unlocked. 


Return Value The return value is zero if the object’s reference count is decreased to zero. 
| Otherwise, it is nonzero. 


Comments The UnlockResource macro is defined in WINDOWS.H as follows: 
#tdefine UnlockResource(h)  GlobalUnlock(h) 


See Also -GlobalUnlock 


Printer Escapes | 


Alphabetic Reference 


Chapter 5 


ABORTDOC 


ABORTDOC 451 


_ This chapter contains an alphabetic list of printer escapes for the Microsoft Win- 


dows operating system, version 3.1. The printer escapes allow applications to 
access certain facilities of output devices that are not directly available through the 
graphics device interface (GDI). The escape calls are made by an application, 
translated by Windows, and then sent to the printer driver. 


short Escape(hdc, ABORTDOC, NULL, NULL, NULL) 


Parameters 


Return Value 


Comments 


See Also” 


The ABORTDOC printer escape is maintained for backwards compatibility. 
Applications written for Windows 3.1 should use the AbortDoc function. 


This escape stops the current job and erases everything the application has written 
to the device since the last ENDDOC escape. 


The ABORTDOC escape should be used to stop: 


= Printing operations that do not specify an Abort function by using the 
SETABORTPROC escape. 


= Printing operations that have not yet reached their first call to the 
NEWFRAME or NEXTBAND escape. 


hdc ; 
| HDC Identifies the device context. 


This escape does not return a value. 


If an application encounters a printing error, it should not try to stop the operation 


_ by using the Escape function with either the ENDDOC or ABORTDOC escape. 


Graphics device interface (GDI) automatically terminates the operation before re- 
turning the error value. | | 7 


If the application displays a dialog box to allow the user to cancel the ee | 


Z tion, it must send the ABORTDOC escape before destroying the dialog box. 


The apphiéation must send the ABORTDOC escape before Mae: the procedure- 


instance. address of the Abort function, if ay 


ae itscape” | 
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BANDINFO 


short Escape(/idc, BANDINFO, sizeof(BANDINFOSTRUCT), [p/nData, IpOutData) 


Parameters 


Return Value 


The BANDINFO printer escape is maintained for backwards compatibility. Appli- 
cations written for Windows 3.1 should send both text and graphics in every band. 


This escape copies information about a device with banding capabilities to a struc- 
ture pointed to by the [pOutData parameter. It is implemented only for devices. 
that use banding to send output to the printer. 


Banding is the property of an output device that allows a page of output to be 
stored in a metafile and divided into bands, each of which is sent to the device to 
create a complete page. 


The information copied to the structure pointed to by the JpOutData parameter in- 
cludes: 


= A value that indicates whether there are graphics in the next band. 
= A value that indicates whether there is text on the page. 


=" A RECT structure that contains a bounding rectangle for all graphics on the 
page. | 


If no data is returned, the JpOutData parameter is NULL. 


The [pInData parameter specifies information sent by the application to the 
printer driver. This information is read by the driver only on the first call to the 
BANDINFO escape on a page. 


hdc 
HDC Identifies the device context. 


lpInData 
BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT structure 
that contains information to be passed to the driver. For more information about 
this structure, see the following Comments section. 

[pOutData ee 
BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT structure 
that contains information returned by the driver. For more information about 
this structure, see the following Comments section. 


The return value specifies the outcome of the escape. This value is 1 if the escape 
is successful. It is zero if the function fails or is not implemented by the driver. 


Comments 
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The BANDINFOSTRUCT structure contains information about the contents of a 
page and supplies a bounding rectangle for graphics on a the page. This structure 
has the following form: 


typedef struct tagBANDINFOSTRUCT { 
BOOL fGraphics; 
BOOL Flext: 
RECT rcGraphics; 

} BANDINFOSTRUCT; 


- Following are the members in the BANDINFOSTRUCT structure: 


fGraphics 
Specifies nonzero if graphics are or are expected to be on the page or in the 
band. Otherwise, it is zero. 


fText 
Specifies nonzero if text is or is expected to be on the page ¢ or in the band. 
Otherwise, it is zero. 


reGraphics 
Contains a RECT structure that supplies a bounding region for all graphics on 
the page. 


The meaning of these members depends on which parameter contains the struc- 
ture, as follows. 


Member ‘When used in IpInData When used in [pOutData 


fGraphics Nonzero if the application in- Nonzero if the driver informs 
forms the driver that graphics are __ the application that it expects 
on the page graphics in this band 

fText Nonzero if the application in- Nonzero if the driver informs the 
forms the driver that text is on ~ application that it expects text in 
the page this band 


reGraphics Bounding rectangle supplied for No valid return data 


all graphics on the page 


_ An application should call this escape immediately after each call to the NEXT- 
_ BAND escape. The BANDINFO escape is in reference to the band that the driver 


returned to the NEXTBAND escape. 


; An application should use this escape in the following manner: 


= On the first band, the driver may give the application a full- -page band and ask 
for text only (the {Graphics member is set to zero and the fText member 1 is set 
to nonzero). Then the ie application sends only text to the driver. 
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BEGIN_ PATH 


= If in the first band the application indicates that it has graphics (the {Graphics 
member is set to nonzero) or the driver encounters vector fonts, the driver 
bands the rest of the page. 


= If there are no graphics or vector fonts, the next NEXTBAND escape returns 
an empty rectangle to indicate that the application should move on to the next 
page. 

= If there are graphics but no vector fonts (the application sets the fGraphics 
member to nonzero, but there are no graphics in the first full-page text band), 
the driver may optionally band only into the rectangle the application passes for 
subsequent bands. This rectangle bounds all graphics on the page. 


= If there are vector fonts, the driver bands the entire width and depth of the page 
with the ffext member set to nonzero. It also sets the fGraphics flag to non- 
zero if the application has set it. 


_ The driver assumes that an application using the BANDINFO escape only sends 


text in the first full-page text band because that is all the driver has requested. 
Therefore, if the driver encounters a vector font or graphics in the band, it assumes 
they were generated by a text primitive and sets the fTfext member to nonzero for 
all subsequent graphics bands, so they can be output as graphics. If the application 
does not meet this expectation, the image still generates properly, but the driver 
spends time sending spurious text primitives to graphics bands. 


Older drivers written before the BANDINFO escape was designed use full-page 
banding for text. If a particular driver does not support the BANDINFO escape | 
but sets the RC_BANDING raster capability, the application can detect full-page 
banding for text by determining if the first band on the page covers the entire page. 


BEGIN PATH 


short Escape(hdc, BEGIN_ PATH, NULL, NULL, NULL) | 


The BEGIN_ PATH printer escape opens a path. A path is a connected sequence 


of primitives drawn in succession to form a single polyline or polygon. Paths 
enable applications to draw complex borders, filled shapes, and clipping regions 
by supplying a collection of other primitives to define the desired shape. 


Parameters 


Return Value 


Comments 
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Printer escapes supporting paths enable applications to render images on sophisti- 
cated devices, such as PostScript printers, without generating huge polygons to 


simulate the images. 


To draw a path, an application first issues the BEGIN_ PATH escape. Then it 
draws the primitives defining the border of the desired shape and issues an 
END_PATH escape, which includes a parameter specifying how the path is to be 
rendered. 


hdc 
HDC Identifies the device context. 


The return value specifies the current path nesting level. This value is the number 


of calls to the BEGIN_ PATH escape without a corresponding call to the © 


END_ PATH escape if the escape is successful. Otherwise, the return value is 
zero. 


This escape is used only by PostScript printer drivers. 


An application may begin a subpath within another path. If the subpath is closed, it — 
is treated just like a polygon. If i it 1S open, it is treated just like a polyline. 


An abpli¢ation may use the CLIP_ TO_PATH escape to define a clipping region 
corresponding to the interior or exterior of the currently open path. | 


CLIP TO PATH 


short Escape(idc, CLIP_TO_PATH, sizeof(int), [pClip Mode, NULL) 


The CLIP_TO_ PATH printer escape defines a clipping region bounded by the 
currently open path. It enables the application to save and restore the current clip- 
ping region and to set up an inclusive or exclusive clipping region bounded by the 
currently open path. If the path defines an inclusive clipping region, portions of 
primitives falling outside the interior bounded by the path are clipped. If the path 
defines an exclusive clipping region, portions of primitives falling inside the inte- — 
rior are clipped. | 
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Parameters hdc | 
HDC Identifies the device context. 
lpClipMode 
LPINT Points to a short integer that specifies the clipping mode. It can be one 
of the following values: 


Value | Meaning | 
CLIP_SAVE (0) Saves the current clipping region. 
CLIP_RESTORE (1) Restores the previous clipping region. 


CLIP_INCLUSIVE (2) Sets an inclusive clipping region. 
CLIP_EXCLUSIVE (3) Sets an exclusive clipping region. 


Return Value The return value specifies the outcome of the escape. This value is nonzero if the 
escape is successful. Otherwise, it is zero. | 


Comments This escape is used only by PostScript printer drivers. 


To clip a set of primitives against a path, an application should follow these steps: 
. Save the current clipping region by using the CLIP_TO_ PATH escape. 

. Begin a path with the BEGIN_ PATH escape. 

. Draw the primitives bounding the clipping region. | 

. Close the path with the END_ PATH escape. 

. Set the clipping region by using the CLIP_TO_ PATH escape. 

. Draw the primitives to be clipped. 
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. Restore the original clipping region by using the CLIP_TO_PATH escape. 


DEVICEDATA 


short Escape(idc, DEVICEDATA, nCount, IpInData, lpOutData) 


The DEVICEDATA printer escape is identical to the PASSTHROUGH escape. 
For further information, see the description of PASSTHROUGH. 
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DRAFTMODE 


short Escape(idc, DRAFTMODE, sizeof(int), /pDraftMode, NULL) 


Parameters 


Return Value 


Comments 


The DRAFTMODE printer escape turns draft mode off or on. Turning draft mode 
on instructs the driver to print faster and with lower quality, if necessary. The draft 
mode can be changed only at page boundaries (for example, after a NEWFRAME 
escape directing the driver to advance to a new page). | 


hdc 
HDC Identifies the device context. 

[pDraftMode 
LPINT Points to a short a that specifies the draft mode. It can be one of 
the following values: 


Value Meaning 
0 Specifies draft mode off. 
1 Specifies draft mode on. 


The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. Otherwise, it is zero or negative. 


The default draft mode is off. 


DRAWPATTERNRECT 


short Escape(idc, DRAWPATTERNRECT, sizeof(PRECTSTRUCT), ipInData, NULL) | 


Parameters 


The DRAWPATTERNRECT printer escape creates a pattern, gray scale, or 
solid black rectangle by using the pattern and rule capabilities of Page Control 
Language (PCL) on Hewlett-Packard LaserJet or LaserJet-compatible printers. 
A gray scale is a gray pattern that contains a specific mixture of black and white 
pixels. 


hdc vs 

HDC Identifies the device context. 

[pInData 
PRECT_STRUCT FAR * Points to a PRECT_STRUCT structure that de- 
scribes the rectangle. For more information on this structure, see the following 
Comments section. 
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Return Value 


Comments 


Comments 


The return value specifies the outcome of the escape. This value is 1 if the escape 
is successful. Otherwise, it is zero. 


The [pInData parameter points to a PRECT_STRUCT structure that defines the 
rectangle to be created. This structure has the following form: 


struct PRECT_STRUCT { 
POINT ptPosition; 
POINT ptSize; 
WORD wStyle; 
WORD wPattern; 
hs 


Following are the members in the PRECT_STRUCT structure: 


ptPosition | 
Specifies the upper-left corner of the rectangle. 
ptSize | 
Specifies the lower-right corner of the rectangle. 
wstyle | | 
Specifies the type of pattern. It can be one of the following values: 
Value Meaning | 
0 Black rule 
1 White rule that erases bitmap data previously written to same area (avail- 
able on the HP LaserJet IIP only) 
2 Gray scale 
3 HP-defined 
wPattern 


Specifies the pattern. It is ignored for a black rule. It specifies the percentage of 
gray for a gray-scale pattern. It represents one of six patterns defined by 
Hewlett-Packard. | 


_ The output of tte DRAWPATTERNRECT escape does not go through the 


graphics banding bitmap; it is sent to the printer in the text band. An application 
can use this escape to print line and block graphics without using graphics banding 
at all. Because many applications use only horizontal and vertical lines or blocks 
in graphic output, this is a significant optimization. 


An application should use the QUERYESCSUPPORT escape to determine 
whether a device is capable of drawing patterns and rules before using the DRAW- 
PATTERNRECT escape. If an application uses the BANDINFO escape, all pat- 
terns and rectangles sent by using DRAWPATTERNRECT should be treated as 


text and sent on a text band. 
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Applications that use tte DRAWPATTERNRECT escape must observe two 
limitations. First, rules drawn with DRAWPATTERNRECT are not subject to 
clipping regions in the device context. Second, applications should not try to erase 
patterns and rules created with DRAWPATTERNRECT by placing opaque ob- 
jects over them. If the printer supports white rules, these can be used to erase pat- 
terns created by DRAWPATTERNRECT. If the printer does not support white 
rules, there is no method for erasing these patterns. 


If an application cannot use the DRAWPATTERNRECT escape, it should gener- 
ally use the PatBit function instead. (If PatBlt is used to print a black rectangle, 
the application should use the BLACKNESS raster operator.) If the device is a 
plotter, the application should use the Rectangle function. 


ENABLEDUPLEX 


short Escape(hdc, ENABLEDUPLEX, sizeof(WORD), /[pInData, NULL) 


Parameters 


Return Value ; 


The ENABLEDUPLEX printer escape is maintained for backwards compati- 
bility. Applications written for Windows 3.1 should use the ExtDeviceMode 
function. An application can determine whether an output device is capable of 
creating duplex output by checking the DM_DUPLEX< bit of the dmFields mem- 


_ ber in the DEVMODE structure. 


This escape enables the duplex printing capabilities of a printer. A device that | 
possesses duplex printing capabilities is able to print on both sides of the output 
medium. 


hdc 
HDC Identifies the device context. 

[pInData 
LPWORD Points to an unsigned 16-bit integer that specifies whether duplex or 
simplex printing is used. It can be one of the following values: 


Value §§$Meaning 
0 Simplex 
1 Duplex with vertical binding 


~ 2. ~~ Duplex with horizontal binding | 


The return value specifies the outcome of the oe This value is 1 if the escape 
is successful. Otherwise, it is Zero. 
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Comments 


_ An application should use the QUERYESCSUPPORT escape to determine 


whether an output device is capable of creating duplex output. If QUERY- 
ESCSUPPORT returns a nonzero value, the application should send the 
ENABLEDUPLEX escape even if simplex printing is desired. This procedure 
guarantees replacement of any values set in the driver-specific dialog box. If 
duplex printing is enabled and an uneven number of NEXTFRAME escapes are 
sent to the driver prior to the ENDDOC escape, the driver ejects an additional 
page before ending the print job. 


ENABLEPAIRKERNING 


short Escape(hdc, ENABLEPAIRKERNING, sizeof(int), [pNewKernFlag, [pOldKernFlag) 


Parameters 


Return Value 


Comments 


The ENABLEPAIRKERNING printer escape enables or disables the ability of 
the driver to kern character pairs automatically. Kerning is the process of adding 
or subtracting space between characters in a string of text. 


When pair kerning is enabled, the driver automatically kerns those pairs of charac- 
ters that are listed in the character-pair kerning table for the font. The driver re- 
flects this kerning both on the printer and in the Get TextExtent function calls. 


hdc 
HDC Identifies the device context. 


IpNewKernFlag — 
LPINT Points to a short-integer value that specifies whether automatic pair 
kerning is to be enabled (1) or disabled (zero). 


lpOldKernFlag 
LPINT Points to a short-integer value that receives the previous automatic pair- 
kerning value. 


The return value specifies the outcome of the escape. This value is 1 if the escape 
is successful. It is zero if the escape is not successful or not implemented. 


The default state of this escape is zero; automatic character-pair kerning is dis- 
abled. | 


A driver does not have to support the ENABLEPAIRKERNING escape just be- 
cause it supplies the character-pair kerning table to the application by using the 
GETPAIRKERNTABLE escape. When the GETPAIRKERNTABLE escape is 
supported but the ENABLEPAIRKERNING escape is not, the application must 
properly space the kerned characters on the output device by using the Ext- | 
TextOut function. oo 
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ENABLERELATIVEWIDTHS 


_ short Escape(hdc, ENABLERELATIVEWIDTHS, sizeof(int), [pNew WidthF lag, IpOldWidthFlag) 


Parameters 


Return Value 


Comments 


The ENABLERELATIVEWIDTHS printer escape enables or disables relative 
character widths. When relative widths are disabled (the default), the width of 
each character can be expressed as a number of device units. This method 
guarantees that the extent of a string will equal the sum of the extents of the char- 
acters in the string. This allows applications to build an extent table by using one- 
character GetTextExtent function calls. 


When relative widths are enabled, the sum of a string may not equal the sum of the 
widths of the characters. Applications that enable this feature are expected to re- 
trieve the extent table for the font and compute relatively scaled string widths. 


hdc 


HDC Identifies the device context. 


IpNewWidthF lag 
LPINT Points to a short integer that specifies whether relative widths are to be 
enabled (1) or disabled (zero). 


[pOldWidthF lag : 
LPINT Points to a short integer that receives the previous relative character 
width value. 


The return value specifies the outcome of the escape. This value is 1 if the escape 
is successful. It is zero if the escape is not successful or not implemented. 


The default state of this escape is zero; relative character widths are disabled. 


When the ENABLERELATIVEWIDTHS escape is enabled, the values specified 
as font units and accepted and returned by the escapes described in this chapter are 
returned in the relative units of the font. | 


It is assumed that only linear-scaling devices are dealt with in a relative mode. 


Nonlinear-scaling devices do not implement this escape. | 
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ENDDOC 


short Escape(jidc, ENDDOC, NULL, NULL, NULL) 


The ENDDOC printer escape is maintained for backwards compatibility. Applica- 
tions written for Windows 3.1 should use the EndDoc function. 


This escape ends a print job started by a STARTDOC escape. 


Parameters hdc 
HDC Identifies the device context. . 


Return Value — The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. Otherwise, it is zero or negative. 


Comments The ENDDOC escape should not be used inside metafiles. 


END_PATH 


short Escape(hdc, END_ PATH, sizeof(PATH_INFO), /pInData, NULL) 


The END_ PATH printer escape ends a path. A path is a connected sequence of 
primitives drawn in succession to form a single polyline or polygon. Paths enable 
applications to draw complex borders, filled shapes, and clipping regions by sup- 
plying a collection of other primitives to define the desired shape. 


Printer escapes that support paths enable applications to render images on sophisti- 
cated devices, such as PostScript printers, without generating huge polygons to 
simulate them. 


To draw a path, an application first issues the BEGIN_ PATH escape. Then it 
draws the primitives defining the border of the desired shape and issues an 
END_ PATH escape. 


The END_PATH escape takes, as a parameter, a pointer to a structure specifying 
the manner in which the path is to be rendered. The structure specifies whether or 
not the path is to be drawn and whether it is open or closed. Open paths define 
polylines, and closed paths define fillable polygons. 


Parameters hdc 
ee HDC Identifies the device context. 


Return Value — 


Comments 
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[pInData 
PATH_INFO FAR * Points to a PATH_INFO structure that defines how the 
path i is to be rendered. For more information about this structure, see the follow- 
ing Comments section. 


The return value specifies the current path nesting level. This value is the number 
of BEGIN_ PATH escape calls without a por entet END_ PATH call if the 
escape is successful. Otherwise, it is —1. 


This escape is used only by PostScript printer drivers. _ 


An application may begin a subpath within another path. If the subpath is closed, it 
is treated just like a polygon. If it is open, it is treated just like a polyline. 


An application may use the CLIP_TO_PATH escape to define a clipping region 
corresponding to the interior or exterior of the currently open path. 


The [pInData parameter points to a PATH_INFO structure that specifies how to 
render the path. This structure has the following form: 


struct PATH_INFO { 


short RenderMode; 
BYTE FillMode; 
BYTE BkMode; 
LOGPEN Pen; 


LOGBRUSH Brush; 
DWORD BkColor; 
bs 


Following are the members in the PATH_INFO structure: 


~ RenderMode 
Specifies how the path is to be rendered. It can be one of the following values: 
Value Meaning 
NO_DISPLAY (0) — Pathis not drawn. 
OPEN (1) Path is drawn as an open polygon. 
CLOSED (2) Path is drawn as a closed polygon. 
FillMode — 


Specifies how the path is to be filled. It can be one of the followane values: 
Value Meaning | 


ALTERNATE (1) Fill is done using the alternate fill algorithm. 
WINDING (2) _Fill is done using the winding fill algorithm. 
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BkMode 
Specifies the background mode for filling the path. It can be one oe the follow- 
ing values: 
Value Meaning | 
OPAQUE | Background is filled with the background color before the | 


brush is drawn. 
TRANSPARENT ___ Background is not changed. 


Pen 
Specifies the pen with which the path is to be drawn. If the RenderMode func- 
tion is set to the NO_DISPLAY value, the pen is ignored. 


Brush 
Specifies the btish with which the path i is to be filled. If the RenderMode func- 
tion is set to the NO_DISPLAY or OPEN value, the brush is ignored. 


BkColor 
Specifies the color with which the path is filled if the BkMode function is set to 
the OPAQUE value. 


ENUMPAPERBINS 


short Escape(idc, ENUMPAPERBINS, sizeof(int), JpNumBins, lpOutData) 


~The ENUMPAPERBINS printer escape is maintained for backwards compati- 
bility. Applications written for Windows 3.1 should call the DeviceCapabilities 
function with the DC_BINNAMES index to retrieve the number ot available paper 
_ bins and the name of each bin. | 


This escape retrieves attribute information about a specified number of paper bins. 
The GETSETPAPERBINS escape retrieves the number of bins available ona 
printer. 


- Parameters hdc 
HDC Identifies the device context. 


lpNumBins — | \ 
LPINT Points to an integer that specifies the number of bins for which informa- 
tion is to be retrieved. 


IpOutData | 
LPSTR Points to a structure to which information about the paper bins is 
copied. The size of the structure depends on the number of bins for which infor- 


Return Value 


Comments 
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mation was requested. For a description of this structure, see the following 
Comments section. 


The return value specifies the outcome of the escape. This value is 1 if the escape 


~ 1s successful. It is zero if the escape is not successful or not implemented. 


The structure to which the IpOutData parameter points consists of two arrays. The 
first is an array of short integers containing the paper-bin identifier numbers in the 
following form: 


short BinList[cBinMax] 


The number of integers in the array (the cBinMax value) is equal to the value 
pointed to by the jpNumBins parameter. — 


The second array in the structure to which /pOutData points is an array of charac- 
ters in the following form: 


char PaperNames[cBinMax][cchBinName ] 


The cBinMax value is equal to the value pointed to by the IpNumBins parameter. 
The cchBinName value is the length of each string (currently 24). | 
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short Escape(hdc, ENUMPAPERMETRICS, sizeof(int), IpMode, [pOutData) 


Parameters | 


The ENUMPAPERMETRICS printer escape performs one of two functions 
according to the mode: 


= Jt determines the number of paper types supported and returns this value, which 


can then be used to allocate an array of RECT structures. 


= It returns one or more RECT structures that define the areas on the page that 
can receive an image. 


This escape is provided only for backward compatibility. An application should 
call the DeviceCapabilities function with the DC_PAPERSIZE index to discover 
the number of available paper sizes and the dimensions of each size. | 


hdc 


HDC Identifies the device context. | 
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Return Value 


lpMode 
LPINT Points to an integer that specifies the mode for the escape. It can be one 
of the following values: 


Value Meaning | 

0 Return value indicates how many RECT structures are required to con- 
tain the information about the available paper types. 

1 Array of RECT structures to which the JpOutData parameter points is 


filled with the information. 


[pOutData | 


- LPRECT Points to an array of RECT structures that return all the areas 
capable of receiving an image. 


The return value is positive if the escape is successful. The value is zero if the 
escape is not implemented and negative if an error occurred. 


EPSPRINTING 


short Escape(/idc, EPSPRIN TING, sizeof(BOOL), /pBool, NULL) 


Parameters 


Return Value 


Comments 


The EPSPRINTING printer escape suppresses the output of the Windows Post- 
Script header control section, which is about 7K. If an application uses this escape, 
no graphics device interface (GDJ) calls are allowed. 


hdc 
HDC Identifies the device context. 


lpBool 
BOOL FAR * Points to a Boolean value that indicates whether downloading 
should be enabled (nonzero) or disabled (zero). 


The return value is positive if the escape is successful. This value is zero if the 
escape is not implemented and negative if an error occurred. 


This escape is used only by PostScript printer drivers. 
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EXT DEVICE CAPS 


short Escape(idc, EXT_DEVICE_ CAPS, sizeof(int), [pIndex, IpCaps) 


The EXT_DEVICE_ CAPS printer escape retrieves information about device- 
specific capabilities. It supplements the GetDeviceCaps function. 


Parameters hdc 


HDC Identifies the device context. 


lpIndex 


LPINT Points to a short integer that specifies the index of the capability to be 
retrieved. It can be any one of the following values: 


Value 


R2_CAPS (1) 


PATTERN_CAPS (2) 


PATH_CAPS (3) 


POLYGON_CAPS (4) 


Meaning 


The /pCaps parameter indicates which of the 16 
binary raster operations the device driver sup- — 
ports. A bit will be set for each supported raster 
operation. For further information, see the de- 
scription of the SetROP2 function in the 
Microsoft Windows Programmer. ‘) RCTS: 
Volume 2. 


The [pCaps parameter returns the maximum di- 
mensions of a pattern brush bitmap. The low- 


_ order word of the capability value contains the 


maximum width of a pattern brush bitmap, and 
the high-order word contains the maximum 
height. 


The [pCaps eararieies indicates whether the 
device is capable of creating paths by using 
alternate and winding interiors, and whether the 
device can do exclusive or inclusive clipping to 
path interiors. The path capabilities are ob- 
tained by using the logical OR operation on the 
following values: 


PATH_ALTERNATE (1) | 
PATH_WINDING (2) 
PATH_INCLUSIVE (4) 
PATH_EXCLUSIVE (8) | 


_ The JpCaps parameter returns the maximum — 


number of polygon points supported by the © 
device. The capability value is an unsigned 


value specifying the maximum number of 


points. 
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Value Meaning 


PATTERN_COLOR_CAPS (5) The [pCaps parameter indicates whether the 
device can convert monochrome pattern bit- 
maps to color. The capability value is 1 if the 
device can do pattern bitmap color conversions 
and zero if it cannot. 


R2_TEXT_CAPS (6) The [pCaps parameter indicates whether the 
device is capable of performing binary raster 
operations on text. The low-order word of the 
capability value specifies which raster opera- 
tions are supported for text. A bit is set for each 
supported raster operation, as in the R2_CAPS 
escape. The high-order word specifies the type 
of text to which the raster capabilities apply. It 
is obtained by applying the logical OR opera- 
tion to the following values together: 
RASTER_TEXT (1) 

DEVICE_TEXT (2) 
| VECTOR_TEXT (4) 

POLYMODE_CAPS (7) — The /pcaps parameter indicates which poly 
modes are supported by the printer driver. The 
capability value is obtained by using the bitwise 
OR operator to combine a bit in the correspond- 

‘ing position for each supported poly mode. For 
example, if the printer supports the 
PM_POLYSCANLINE and PM_BEZIER poly 
modes, the capability value would be: 


(1 << PM_POLYSCANLINE) | (PM_BEZIER) 


| [pCaps 
LPDWORD Points to a 32-bit integer to which the capabilities will be copied. 


Return Value The return value is nonzero if the specified extended capability is supported. This 
value is zero if the capability is not supported. 


Comments This escape is used only by PostScript printer drivers. 
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EXTTEXTOUT 


short Escape(hdc, EXTTEXTOUT, sizeof(EXTTEXT_ STRUCT), [pInData, NULL) 


The EXTTEXTOUT printer escape provides an efficient way for an application 
to call the graphics device interface (GDI) TextOut function when justification, 
letter spacing, or kerning is involved. 


This function is provided only for backward compatibility. New applications 
should use the GDI ExtTextOut function instead. 


Parameters hdc 
HDC Identifies the device context. 


lpInData 
EXTTEXT_STRUCT FAR * Points to an EXTTEXT_STRUCT structure 
that specifies the initial position, characters, and character widths of the string. 
For more information about this structure, see the following Comments section. 


Return Value The return value specifies the outcome of the escape. This value is 1 if the escape 
| is successful. It is zero if the escape is not successful or not implemented. 


Comments The EXTTEXT_ STRUCT structure has the following form: 


struct EXTTEXT_ STRUCT { 
WORD X; 
WORD y; 
LPWORD IpText; 
LPWORD IpWidths; 

3 


Following are the members in the EXTTEXT_STRUCT structure: 


x 
Specifies the x-coordinate of the upper-left corner of the string.» starting point. 


Specifies the y-coordinate of the ped eitaae corner of the string’ s starting point. 


, IpText 
Points to an array of cch character codes, where cch is the number of bytes i in 
the string (cch is also the number of words in the width array). 
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Ip Widths | 7 
Points to an array of cch character widths to use when printing the string. The 
first character appears at (x,y), the second at (x + IpWidths[0],y), the third at 
(x + IpWidths[0] + IpWidths[1],y), and so on. These character widths are 
specified in the font units of the currently selected font. (The character widths 
are always equal to device units, unless the application has enabled relative 
character widths.) | 


The units contained in the width array are specified as font units of the device. 


FLUSHOUTPUT 


short Escape(hdc, FLUSHOUTPUT, NULL, NULL, NULL) 
The FLUSHOUTPUT printer escape clears all output from the device’s buffer. 


Parameters hdc 
HDC Identifies the device context. 


Return Value The return value specifies the outcome of the escape. This value is greater than 
zero if the escape is successful. Otherwise, it is less than zero. 


GETCOLORTABLE 


short Escape(hdc, GETCOLORTABLE, sizeof(int), [pIndex, IpColor) 


The GETCOLORTABLE printer escape retrieves an RGB color-table entry and 
copies it to the location specified by the JpColor parameter. _ 
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Parameters — hdc : 
, HDC Identifies the device context. 


lpIndex 
‘ LPINT Points to a short integer that specifies the index of a color-table entry. 
Color-table indexes start at zero for the first table entry. 


lpColor 
LPDWORD Points to the long integer that will receive the RGB color value 
for the given entry. 


Return Value The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. Otherwise, it is negative. 


GETEXTENDEDTEXTMETRICS 


short Escape(idc, GETEXTENDEDTEXTMETRICS, sizeof(WORD), ip/nData, lpOutData) 


The GETEXTENDEDTEXTMETRICS printer escape fills the buffer pointed to — 
by the /pOutData parameter with the extended text metrics for the selected font. 


Parameters hdc 


HDC Identifies the device context. 


[pInData 
LPWORD Points to an unsigned 16-bit integer that specifies the number of - 
bytes pointed to by the ipOutData parameter. 


[pOutData | 
EXTTEXTMETRIC FAR * Points to an EXTTEXTMETRIC structure. For 
more information about this structure, see the following Comments section. 


Return Value — The return value specifies the number of bytes copied to the buffer pointed to by 
SONGS the IpOutData parameter. This value will never exceed that specified in the nSize 
member pointed to by the [p/nData parameter. The return value is zero if the 
selected font does not have the extended text metrics or it the escape fails or is not 
- implemented. : 
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Comments The [pOutData parameter points to an EXTTEXTMETRIC structure, which has 
the following form: 


struct EXTTEXTMETRIC { 
short etmSize; 
short etmPointSize; 
short etmOrientation; 
short etmMasterHeight; 
short etmMinScale; 
short etmMaxScale; 
short etmMasterUnits; 
short etmCapHeight; 
short etmXHeight; 
short etmLowerCaseAscent; 
short etmLowerCaseDescent; 
short etmSlant; 
short etmSuperScript; 
short etmSubScript; 
short etmSuperScriptSize; 
short etmSubScriptSize; 
short etmUnderlineOffset; 
short etmUnderlineWidth; 
short etmDoubleUpperUnderlineOffset; 
short etmDoubleLowerUnderlineOffset; 
short etmDoubleUpperUnder] ineWidth; 
short etmDoubleLowerUnderlinewWidth; 
short etmStrikeOutOffset; 
short etmStrikeQOutWidth; 
WORD etmKernPairs; 
WORD etmKernTracks; 

sa 


Following are the members in the EXTTEXTMETRIC structure: 


etmSize | 
Specifies the size of the structure, in bytes. 


etmPointSize 
Specifies the nominal point size of this font, in twips (1/20 of a point, or 1/1440 
inch). This is the intended size of the font; the actual size may differ slightly de- 
pending on the resolution of the device. 


_etmOrientation | 
Specifies the orientation of the font. The etmOrientation member may be any 
of the following values: 


Value Meaning 
0 Either orientation 
1 Portrait 


2 Landscape 
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These values refer to the ability of this font to be placed on a page with the 
given orientation. A portrait page has a height that is greater than its width. A 
landscape page has a width that is greater than its height. 


etmMasterHeight 
Specifies the font size, in device units, for which the values in this font’s extent 
table are exact. 


etmMinScale | 
Specifies the minimum valid size for this font. The following equation illus- 
trates how the minimum point size is determined: 


smallest point size = (etmMinScale * 72) / dfV. ertRes 


The value 72 represents the number of points per inch. The dfVertRes value is 
the number of dots per inch. 


etmMaxScale 
Specifies the maximum valid size for this font. The following equation illus- 
trates how the maximum point size is determined: 


largest point size = (etmMaxScale * 72) / dfVertRes 


The value 72 represents the number of points per inch. The dfVertRes value is | 
the number of dots per inch. | 


etmMaster Units 
Specifies the integer number of units per em where an em equals the value of 
the etmMasterHeight member. (That is, etmMasterUnits is emtMaster- 
Height expressed in font units instead of device units.) 


etmCapHeight 
Specifies the height, in ‘font units, of uppercase characters in the font. Typically, 
this is the height of capital H. 


etmXHeight 
Specifies the height, in font units, of lowercase characters in the font. Typically, 
this is the height of lowercase x. | 


etmLowerCaseAscent 
Specifies the distance, in font units, that the ascender of lowercase letters eXx- 
tends above the base line. Typically, this is the height of lowercase d. 


etmLowerCaseDescent 
Specifies the distance, in font units, that the descender of lowercase letters ex- 
tends below the base line. Typically, this is specified for the descender of lower- 
case p. 


etmSlant 
Specifies, for an italic or slanted font, the angle of the slant measured in tenths 
of a degree clockwise from the upright version of the font. : 
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etmSuperScript 
Specifies, in font units, the recommended amount to offset superscript charac- 
ters from the base line. This is typically a negative value. 


etmSubScript 
Specifies, in font units, the recommended amount to o offset subscript characters 
from the base line. This is typically a positive value. 


etmSuperScriptSize 
Specifies, in font units, the recommended size of superscript characters for this 
font. : 


etmSubScriptSize 
Specifies, in font units, the recommended size of subscript characters for this 
font. 


etmUnderlineOffset 
Specifies, in font units, the offset downward from the base line where the top of 
a single underline bar should appear. 


etmUnderlineWidth 
Specifies, in font units, the thickness of the underline bar. 


etmDoubleUpperUnderlineOfiset 
Specifies the offset, in font units, downward from the base line where the top of 
the upper double-underline bar should appear. 


etmDoubleLowerUnderlineOffset 
Specifies the offset, in font units, downward from the base line where the top of 
the lower double-underline bar should appear. 


etmDoubleUpper Underline Width 
Specifies, in font units, the thickness of the upper underline bar. 


etmDoubleLowerUnderlineWidth 
Specifies, in font units, the thickness of the lower underline bar. 


etmStrikeOutOffset 
Specifies, in font units, the offset upward from the base line where the top of a 
strikeout bar should appear. 


etmStrikeOutWidth 
Specifies the thickness, in font units, of the strikeout bar. 


etmKernPairs 
_ Specifies the number of character kerning pairs defined for this font. An appli- 
cation can use this value to calculate the size of the pair-kern table returned by 
the GETPAIRKERNTABLE escape. It will not be greater than 512 kerning 
pairs. 
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etmKernTracks 
Specifies the number of kerning tracks defined for this font. An aeolicaiOn can 
use this value to calculate the size of the track-kern table returned by the GET- 
TRACKKERNTABLE escape. It will not be greater than 16 kerning tracks. 


The values returned in many of the members of the EXTTEXTMETRIC struc- 
ture are affected by whether relative character widths are enabled or disabled. For 
more information, see the description of the ENABLERELATIVEWIDTHS 
escape earlier in this chapter. 


GETEXTENTTABLE 


short Escape(hdc, GETEXTENTTABLE, sizeof(CHAR_RANGE_STRUCT), nes 


lpOutData) 


Parameters 


Return Value 


Comments 


The GETEXTENTTABLE printer escape retrieves the width (extent) of in- 


- dividual characters from a group of consecutive characters in the character set for 


the selected font. 


hdc 
HDC Identifies the device context. 


lpInData 
LPSTR Points to a CHAR_ RANGE _ STRUCT structure that defines the 
range of characters for which the width is to be retrieved. For more information 
about this structure, see the following Comments section. 


lpOutData 
LPINT Points to an array of short integers that receives the character widths. 
The size of the array must be at least (chLast — chFirst + 1). 


The return value specifies the outcome of the escape. This value is | if the escape 
is successful. It is zero if the escape is not successful. If the escape is not imple- 
mented, the return value is zero. 


The /pInData parameter points toa CHAR_RANGE_ STRUCT structure that de- 
fines the range of characters for which the width is to be retrieved. This structure 
has the following form: . 


struct CHAR_RANGE_STRUCT { 
CHAR chFirst; 
CHAR chLast; 

iz 
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Following are the members in the CHAR_RANGE_STRUCT structure: 


chFirst ae 
Specifies the character code of the first character whose width is to be retrieved. 


chLast 
Specifies the character code of the last character whose width is to be retrieved. 


How an application uses the retrieved values depends upon whether relative char- 
acter widths are enabled or disabled. For more information, see the description of 
the ENABLERELATIVEWIDTHS escape, earlier in this chapter. 


GETFACENAME ~ 


short Escape(idc, GETFACENAME, NULL, NULL, /pFaceName) 


Parameters 


Return Value 


Comments 


The GETFACENAME printer escape retrieves the face name of the current physi- 
cal font. 


hdc 
HDC Identifies the device context. 


lpFaceName | 
LPSTR Points to a buffer of characters to receive the face name. This buffer 


must be at least 60 bytes in length. 


The return value is positive if the escape was successful. This value is zero if the 
escape is not implemented or negative if an error occurred. 


This escape is used only by PostScript printer drivers. 


GETPAIRKERNTABLE 


short Escape(hdc, GETPAIRKERNTABLE, NULL, NULL, /pOutData) 


The GETPAIRKERNTABLE printer escape fills the buffer pointed to by the 
[pOutData parameter with the character-pair kerning table for the selected font. 


Parameters 


~ Return Value 


Comments 
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hdc 
HDC Identifies the device context. 


lpOutData 
KERNPAIR FAR * Points to an array of KERNPAIR structures. This 
array must be large enough to accommodate the entire character-pair 
kerning table for the font. The number of character-kerning pairs in the 
font can be obtained from the EXTTEXTMETRIC structure returned by the 
GETEXTENDEDTEXTMETRICS escape. For more information about this 
structure, see the following Comments section. 


The return value specifies the number of KERNPAIR structures copied to the 
buffer. This value is zero if the font does not have kerning pairs defined or the 
escape fails or is not implemented. 


The KERNPAYIR structure has the following form: 


struct KERNPAIR { 
union { ; 
BYTE each [2]; /* ‘each’ and ‘both' share same memory */ 
WORD both; 
} kpPair; 
short kpKernAmount; | 
i 


Following are the members in the KERNPAIR structure: 


each 
Specifies the character codes for the kerning pair. 


both 
Specifies a 16-bit value in which the first character in the ee pair is in the 
low-order byte and the second character is in the high-order byte. - 


kpKernAmount 
Specifies the signed amount that this pair will be kerned if they appear side by 
side in the same font and size. This value is typically negative because pair- 
kerning usually results in two characters being set tighter than normal. _ 


The array of KERNPAIR structures is sorted in eee order by the 
kpPair.both member. 


The values returned in KERNPAIR structures are affected by whether relative 
character widths are enabled or disabled. For more information, see the description 
of the ENABLERELATIVEWIDTHS escape earlier in this chapter. 
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GETPHYSPAGESIZE 


short Escape(idc, GETPHYSPAGESIZE, NULL, NULL, [pDimensions) 


Parameters 


Return Value 


The GETPHYSPAGESIZE printer escape retrieves the physical page size and 
copies it to the location pointed to by the JpDimensions parameter. 


hdc 
HDC Identifies the device context. 


lpDimensions 
LPPOINT Points to a POINT structure that will receive the physical page di- 
mensions (in the current orientation). The x member of the POINT structure re- 
ceives the horizontal size, in device units, and the y member receives the 
vertical size, in device units. 


The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. Otherwise, it is zero or negative. 


-GETPRINTINGOFFSET 


short Escape(hdc, GETPRINTINGOFFSET, NULL, NULL, [pOffset) 


Parameters 


Return Value 


The GETPRINTINGOFFSET printer escape retrieves the offset from the upper- 
left corner of the physical page where the actual printing or drawing begins. This 
escape is generally not useful for devices that allow the user to set the origin of the 
printable area directly. 


hdc 
HDC Identifies the device context. 

lpOffset | | 
LPPOINT Points to a POINT structure that will receive the printing offset (in 
the current orientation). The x member of the POINT structure receives the 
horizontal coordinate of the printing offset, in device units, and the y member 
receives the vertical coordinate of the printing offset, in device units. 


The return value specifies the outcome of the escape. This value is positive if the 


escape is successful. Otherwise, it is zero or negative. 
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GETSCALINGFACTOR 


short Escape(hdc, GETSCALINGFACTOR, NULL, NULL, /pFactors) 


Parameters 


Return Value 


The GETSCALINGFACTOR printer escape retrieves the scaling factors for the 
X-axis and y-axis of a printing device. For each scaling factor, the escape copies an 
exponent of 2 to the location pointed to by the /pF actors parameter. For example, 
the value 3 is copied to /pFactors if the scaling factor is 8. | 


Scaling factors are used by printing devices that support graphics at a smaller reso- 
lution than text. 


hdc | 
HDC Identifies the device context. 


lpFactors 
LPPOINT Points to the POIN T structure that will receive the scaling factor. 
The x member of the POINT structure receives the scaling factor for the x-axis 
and the y oe receives the scaling factor for the y-axis. 


The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. Otherwise, it is zero or negative. 


- GETSETPAPERBINS 


short Escape(idc, GETSETPAPERBINS, nCount, IpInData, lpOutData) 


Parameters 


The GETSETPAPERBINS printer escape is maintained for backwards compati- 
bility. Applications written for Windows 3.1 should call the DeviceCapabilities 
function with the DC_BINS index to retrieve the number of available paper bins 
and use the ExtDeviceMode function to set the current paper bin. 


This escape retrieves the number of paper bins available on a printer and sets the 
current paper bin. For more information about actions performed by this escape, 
see the following Comments section. 


hdc : 
HDC Identifies the device context. 


~ nCount 


int Specifies the number of bytes pointed to ey the IpInData parameter. 
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Return Value 


Comments 


lpInData 
BinInfo FAR * Points to a BinInfo structure that specifies the new paper bin. 
It may be set to NULL. For more information about this structure, see the fol- 
lowing Comments section. 


[lpOutData — 
BinInfo FAR * Points to a BinInfo structure that contains information about 
the current or previous paper bin and the number of bins available. For more in- 
formation about this structure, see the following comments section. 


The return value is positive if the escape is successful. Otherwise, this value is 
Zero or negative. 7 


There are three possible actions for this escape, depending on the values passed in 
the [pInData and [pOutData parameters: 


lpInData = IpOutData Action 


NULL BinInfo Retrieves the number of bins and the number of the current 
bin. 

BinInfo BinInfo Sets the current bin to the number specified in the 
BinNumber member of the structure to which the 
[pInData parameter points and retrieves the number 
of the previous bin. 


BinInfo NULL Sets the current bin to the number specified in the 


BinNumber member of the structure to which the 
[pInData parameter points. 


The BinInfo structure has the following form: 


struct BinInfo { 
int BinNumber; 
int cBins; 
int Reserved; 
int Reserved; 
int Reserved; 
int Reserved; 

as 


Following are the members of the BinInfo structure: 


BinNumber | 
Identifies the current or previous paper bin. 


cBins 
Specifies the number of paper bins available. 


Once a new bin is set, the selection takes effect immediately; the next page printed 
comes from the new bin. 3 
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GETSETPAPERMETRICS 


aon i te GETSETPAPERMETRICS, sizeof(RECT), lpNewPaper, [pPrevPaper) 


Parameters 


Return Value 


The GETSETPAPERMETRICS printer escape sets the paper type according to 
the given paper metrics information. It also retrieves the paper metrics information 
for the current printer. 


This escape is obsolete. Printer drivers written for Windows version 3.0 and later 
may not support this escape. Applications can use the DeviceCapabilities and 
ExtDeviceMode functions to achieve the same functionality. 


This escape expects a RECT structure representing the imageable area of the 
physical page and assumes the origin is situated in the upper-left corner. 


hdc 
HDC Identifies the device context. 


lpNewPaper - 
LPRECT Points to a RECT structure that defines the new imageable area. 


lpPrevPaper 


ee a! Points to a RECT structure that receives the previous imageable area. 


The return value is positive if the escape is successful. The value is zero if the 


escape is not implemented and negative if an error occurs. | 


GETSETPRINTORIENT 


short Escape(idc, GETSETPRINTORIENT, nCount, [pInData, NULL) | 


Parameters 


The GETSETPRINTORIENT printer escape returns or sets the current paper 
orientation. This escape is obsolete. Printer drivers written for Windows version 
3.0 and later may not support this escape. An application should call the 
ExtDeviceMode function instead. | 


hdc 
HDC Identifies the device context. 


nCount — 
short Specifies the number of bytes pointed to by the lpInData parameter. 


482 GETSETSCREENPARAMS 


Return Value 


Comments 


[pInData 
ORIENT FAR * Points to an ORIENT structure that specifies the new paper 
orientation. For a description of this structure, see the following Comments sec- 
tion. It may be set to NULL, in which case the GETSETPRINTORIENT 
escape returns the current paper orientation. 


The return value specifies the current orientation if IpInData is NULL. Otherwise, 
this value is the previous orientation. This value is —1 if the escape fails. 


This escape is provided only for backward compatibility. New applications should 
use the graphics device interface (GDI) DeviceCapabilities and ExtDeviceMode 
functions instead. 


The ORIENT structure has the following form: 


struct ORIENT { 
DWORD Orientation; 
DWORD Reserved; 
DWORD Reserved; 
DWORD Reserved; 
DWORD Reserved; 

is 


The Orientation member can be one of these values: 


Value Meaning 
1 New orientation is portrait. 
2 | New orientation is landscape. 


GETSETSCREENPARAMS 


Short Escape(hdc, GETSETSCREENPARAMS, sizeof(SCREENPARAMS), lpInData, [pOutData) 


Parameters © 


The GETSETSCREENPARAMS printer escape retrieves or sets the current 
screen information for rendering halftones. | 


hdc 


HDC Identifies the device context. 


lpInData 
SCREENPARAMS FAR * Points to a SCREENPARAMS structure that con- 
tains the new screen information. For more information about this structure, see 
the following Comments section. This parameter may be NULL. 


Return Value 


Comments 
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IpOutData 
SCREENPARAMS FAR * Points to aSCREENPARAMS structure that re- 
trieves the previous screen information. For more information about this struc- 
ture, see the following Comments section. This parameter may be NULL. 


The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. Otherwise, it is negative. | 


This escape affects how device-independent bitmaps (DIBs) are rendered and how 
color objects are filled. 


The SCREENPARAMS structure has the following form: 


typedef struct tagSCREENPARAMS { 
int angle; 
int frequency; 

} SCREENPARAMS; 


Following are the members of the SCREENPARAMS structure: 
angle | 
Specifies, in degrees, the angle of the halftone screen. 


frequency 
Specifies, in dots per inch, the screen pba 


GETTECHNOLOGY 


short Escape(idc, GETTECHNOLOGY, NULL, NULL, IpTechnology) 


Parameters 


Return Value 


The GETTECHNOLOGY printer escape retrieves the general technology type — | 
for a printer, which allows an application to perform technology-specific actions. 


_ Applications should avoid using this escape. Printer drivers written for Windows 


version 3.0 and later may not support this escape. 


hdc 
HDC Identifies the device context. 
lpTechnology 


LPSTR Points to a buffer to which the driver copies a null- feraninated ‘string 
containing the printer technology type, such as “PostScript”. 


The return value specifies the outcome of the escape. This value is 1 if the escape 
is successful. It is zero if the escape is not successful or is not implemented. 
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GETTRACKKERNTABLE — 


short Escape(hdc, GETTRACKKERNTABLE, NULL, NULL, pOutData) 


Parameters 


Return Value 


Comments 


The GETTRACKKERNTABLE printer escape fills the buffer pointed to by the 
[pOutData parameter with the track-kerning table for the currently selected font. 


hdc . 

HDC Identifies the device context. 

[pOutdata 
KERNTRACK FAR * Points to an array of KERNTRACK structures. 
This array must be large enough to accommodate all the kerning tracks for the 
font. The number of tracks in the font can be obtained from the EXTTEXT- 
METRIC structure which is returned by the GETEXTENDEDTEXT- 
METRICS escape. For more information about this structure, see the 
following Comments section. 


The return value specifies the number of KERNTRACK structures copied to the 
buffer. This value is zero if the font does not have kerning tracks defined or if the 
escape fails or is not implemented. 


The KERNTRACK structure has the following form: 


struct KERNTRACK {_ 


short Degree; 
Short MinSize; 
— short MinAmount; 
short MaxSize; 
Short MaxAmount; 
h; 


Following are the members in the KERNTRACK structure: 


Degree 
Specifies the amount of track kerning. Increasingly negative values represent 
tighter track kerning, and increasingly positive values represent looser track 
kerning. : 

MinSize | | 
Specifies, in device units, the minimum font size for which linear track kerning 
applies. : 

MinAmount 


Specifies, in font units, the amount of track kerning to apply to font sizes less 
than or equal to the size specified by the MinSize member. 


GETVECTORBRUSHSIZE 485 


MaxSize | 
Specifies, in device units, the maximum font size for which linear track kerning 
applies. 


MaxAmount 
Specifies, in font units, the amount of track kerning to apply to font sizes 
greater than or equal to the size specified by the MaxSize member. 


Between the MinSize and MaxSize font sizes, track kerning is a linear 
function from MinAmount to MaxAmount. The values returned in the 
KERNTRACK structures are affected by whether relative character widths 
are enabled or disabled. For more information, see the description of the 
~ ENABLERELATIVEWIDTHS escape earlier in this chapter. 


GETVECTORBRUSHSIZE 


_ Short Escape(hdc, GETVECTORBRUSHSIZE, sizeof(LOGBRUSH), [pinData, [pOutData) 


The GETVECTORBRUSHSIZE printer escape retrieves, in device units, the 
size of a plotter pen used to fill closed figures. Graphics device interface (GDD 
uses this information to prevent the plotter pen from writing over the borders of 
the figure when filling closed figures. 


Parameters hdc | 
HDC Identifies the device context. 


[pInData 


LOGBRUSH FAR * Points to a LOGBRUSH structure that specifies the 
brush for which data is to be returned. 


[pOutData 
LPPOINT Points to a POINT structure whose y member contains the width of 
the pen, in device units. 


Return Value The return value specifies the outcome of the escape. This value is 1 if the escape 
is successful. It is zero if the escape is not successful or is not implemented. 
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GETVECTORPENSIZE 


short Escape(idc, GETVECTORPEN SIZE, sizeof(LOGPEN), /pinData, [pOutData) 


Parameters 


Return Value 


The GETVECTORPENSIZE printer escape retrieves the size, in device units, of 
a plotter pen. Graphics device interface (GDI) uses this information to prevent 
hatched brush patterns from overwriting the border of a closed figure. 


hdc —_ 
HDC Identifies the device context. 


lpInData 
LOGPEN FAR * Points to a LOGPEN structure that specifies the pen for 
which the width is to be retrieved. 


lpOutData 
LPPOINT Points to a POINT structure that contains in its second word the 
width of the pen, in device units. 


The return value specifies the outcome of the escape. This value is 1 if the escape © 
is successful and zero if the escape is not successful or if it is not implemented. 


MFCOMMENT 


BOOL Escape(hdc, MFCOMMENT, nCount, lp>Comment, NULL) 


Parameters 


Return Value 


The MFCOMMENT printer escape adds a comment to a metafile. 


| hdc 


HDC Identifies the device context for the device on which the metafile appears. 


nCount 
short Specifies the number of characters 1 in the string pointed to by the 
[p Comment parameter. 


lpComment 
LPSTR Points to a string that contains the comment that will appear in the 
metafile. : 


The return value specifies the outcome of the escape. This value is —1 if an error, 
such as insufficient memory or an invalid port specification, occurs. Otherwise, it 
1S positive. 


MOUSETRAILS 


MOUSETRAILS 


short Escape(hdc, MOUSETRAILS, sizeof(WORD), [pTrailSize, NULL) 
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The MOUSETRAILS escape enables or disables mouse trails for display devices. 


Parameters hdc 


HDC Identifies the device context. 


[pTrailSize 


LPINT points to a 16-bit variable containing a value specifying the action to 
take and the number of mouse cursor images to display (trail Se). The variable 
can be one of the following values: 


Value 


1 through 7 


2 


Meaning 


Enables mouse trails and sets the trail size to the specified number. 
A value of 1 requests a single mouse cursor. A value of 2 requests 
that one extra mouse cursor be drawn behind the current mouse cur- 
sor, and so on, up to a maximum of 7 total cursor images. The 
escape sets the MouseTrails entry in the WIN_INI file to the given 
value and returns the new trail size. ) 


Disables mouse trails. The escape sets the MouseTrails entry to the 
negative value of the current trail size (if positive) and returns the 
negative value. 


Enables mouse trails. The display driver reads the MouseTrails entry 
from the [windows] section of the WIN.INI file. If the value of the 
entry is positive, the escape sets the trail size to the given value. If 
the entry is negative, the escape sets the trail size to the entry’s abso- 
lute value and writes the positive value back to WIN.INI. If the 
MouseTrails entry is not found, the escape sets the trail size to 7 and 


- writes a new MouseTrails entry to the WIN.INI file, setting its value 


to 7. The escape then returns the new trail size. 


Disables mouse trails but does not cause the display driver to update 3 


the WIN.INI file. - 


Enables mouse trails but does not cause the display driver to update 


the WIN.INI file. 


Return Value The return alge specifies the new trail size if the escape is successful. The return 
value is ZETO if the escape is not supported. 
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NEWFRAME 


short Escape(idc, NEWFRAME, NULL, NULL, NULL) 


Parameters 


Return Value 


Comments 


The NEWFRAME printer escape is maintained for backwards compatibility. 
Applications written for Windows 3.1 should use the StartPage and EndPage 
functions. 


This escape informs the device that the application has finished writing to a page. 
It is typically used with a printer to direct the device driver to advance to a new 


page. - 


hdc 
HDC Identifies the device context. 


The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. Otherwise, it is one of the following values: 


Value | Meaning 

SP_APPABORT Job was terminated because the application’s Abort func- 
tion returned zero. 

SP_ERROR General error. 

SP_OUTOFDISK Not enough disk space is currently available for spooling, 


and no more space will become available. 
SP_OUTOFMEMORY Not enough memory is available for spooling. 
SP_USERABORT User terminated the job through Print Manager. 


Do not use the NEXTBAND escape with the NEWFRAME escape. For banding 
device drivers, graphics device interface (GDI) replays a metafile to the printer, 
simulating a sequence of NEXTBAND escapes. 


The NEWFRAME escape restores the default values of the device context. Con- 
sequently, if a font other than the default font is selected when the application calls 


the NEWFRAME escape, the application must select the font again following the 


NEWFRAME escape. | 
The NEWFRAME escape should not be used inside metafiles. 
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NEXTBAND 


short Escape(hdc, NEXTBAND, NULL, NULL, [pBandRect) 


The NEXTBAND printer escape informs the device driver that the application has 
finished writing to a band, causing the device driver to send the band to Print 
Manager and return the coordinates of the next band. Applications that process 
banding themselves use this escape. 


Parameters hdc 
HDC Identifies the device context. 


[pBandRect 
LPRECT Points to the RECT structure that will receive the next band coordi- 
nates. The device driver copies the device coordinates of the next band into this 
Structure. 


Return Value The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. A return value of zero indicates that an error occurred. In ad- 
dition, the following error values are defined: 


Value | | Meaning 
SP_APPABORT _ Job was terminated because the application’s Abort func- 
| : tion returned zero. 7 : 
SP_ERROR General error. 
SP_OUTOFDISK Not enough disk space is currently available for spooling, 


: and no more space will become available. 
SP_OUTOFMEMORY Not enough memory is available for spooling. 
SP_USERABORT User terminated the job through Print Manager. 


Comments ~The NEXTBAND escape sets the band rectangle to the empty ee when 
printing reaches the end of a page. 


Do not use the NEWFRAME escape with the NEXTBAND escape. 
The NEXTBAND escape should not be used inside metafiles. 
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PASSTHROUGH 


short Escape(idc, PASSTHROUGH, NULL, /pInData, NULL) 


Parameters 


Return Value 


Comments 


The PASSTHROUGH printer escape allows the application to send data directly 
to the printer, bypassing the standard print-driver code. 


Note To use this escape, an application must have complete information about 
how the particular printer operates. 


hdc | | 
HDC Identifies the device context. 
lpInData 


LPSTR Points to a structure whose first word (16 bits) contains the number of 
_ bytes of input data. The remaining bytes of the structure contain the data itself. 


The return value specifies the number of bytes transferred to the printer if the 


escape is successful. This value is less than or equal to zero if the escape is not 
successful or not implemented. 


There may be restrictions on the kinds of device data an application can send to 
the device without interfering with the operation of the driver. In general, applica- 
tions must avoid resetting the printer or causing the page to be printed. 


It is strongly recommended that applications do not perform actions that consume 
printer memory, such as downloading a font or a macro. 


An application can avoid corrupting its data stream when issuing multiple, con- 
secutive PASSTHROUGH escapes by not accessing the printer any other way 
during the sequence. 


An application can guarantee that the PASSTHROUGH escape will be successful 
if it uses a “save” PostScript operator before sending PASSTHROUGH data and 
a “restore” operator after. Avoiding graphics device interface (GDI) functions be- 
tween calls to the PASSTHROUGH escape and avoiding commands that cause a 
page to eject are other means to ensure that the escape will be successful. | 
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POSTSCRIPT_DATA 


The POSTSCRIPT_ DATA printer escape is identical to the PASSTHROUGH 
escape. 


POSTSCRIPT_IGNORE 


short Escape(hdc, POSTSCRIPT_ IGNORE, NULL, [pfOutput, NULL) 


Parameters 


Return Value 


Comments 


The POSTSCRIPT_IGNORE printer escape sets a flag indicating whether or 


not to suppress output. 


‘hde 


HDC Identifies the device context. 


lpfOutput 
BOOL FAR Points to a flag indicating whether output should be suppressed. 
This value is nonzero to suppress output and zero otherwise. 


The return value specifies the previous setting of the output flag. 


Applications that generate their own PostScript code can use the 
POSTSCRIPT_IGNORE escape to prevent the PostScript device 
driver from generating output. 


QUERYESCSUPPORT 


short Escape(idc, QUERYESCSUPPORT, sizeof(int), [pEscNum, NULL) 


Parameters 


The QUERYESCSUPPORT printer escape determines whether a particular 
escape is implemented by the device driver. 


hdc 
HDC Identifies the device context. 


[lpEscNum 
_LPINT Points to a short integer that specifies the escape function to be checked. 
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Return Value 


The return value specifies ehthes a particular escape is implemented. This value 
is nonzero for implemented escape functions. Otherwise, it is zero. 


If the pEscNum parameter is set to DRAWPATTERNRECT, the return value is 
one of the following values: 


Value Meaning 

0 DRAWPATTERNRECT is not implemented. | 

I DRAWPATTERNRECT is implemented for a printer other than the HP 
LaserJet IIP; this printer supports white rules. 


2 DRAWPATTERNRECT is implemented for the HP LaserJet IIP. 


RESTORE_CTM 


short Escape(idc, RESTORE_CTM, NULL, NULL, NULL) 


Parameters 


Return Value 


Comments 


The RESTORE_CTM printer escape restores the previously saved current trans- 
formation matrix. 


The current transformation matrix controls the manner in which coordinates are 
translated, rotated, and scaled by the device. By using matrices, an application can 
combine these operations in any order to produce the desired mapping for a partic- 
ular picture. | 


hdc 
HDC Identifies the device context. 


The return value specifies the number of SAVE_CTM escape calls without a 


corresponding RESTORE_CT™M call. The return value is —1 if the escape is un- 
successful. 


This escape is used only by PostScript printer drivers. 


Applications should not make any assumptions about the initial contents of the cur- 
rent transformation matrix. 


SAVE_CTM 
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short Escape(idc, SAVE_CTM, NULL, NULL, NULL) 


Parameters 


Return Value 


Comments 


The SAVE_CTM printer escape saves the current transformation matrix. 


The current transformation matrix controls the manner in which coordinates are 
translated, rotated, and scaled by the device. By using matrices, an application can 
combine these operations in any order to produce the desired mapping for a partic- 
ular picture. 


An application can restore the matrix by using the RESTORE_ CTM escape. 


An application typically saves the current transformation matrix before changing 
it. This allows the application to restore the previous state upon ne ae ofa 
particular operation. | 


hdc 


HDC Identifies the device context. 


The return value specifies the number of SAVE_CTM escape calls without a 
corresponding RESTORE_CTM call. The return value is zero if the escape is un- 
successful. 


This escape is used only by PostScript printer drivers. 


Applications should not make any assumptions about the initial contents of the cur- 
rent transformation matrix. 


Applications are expected to restore the contents of the current transformation 
matrix. 


SELECTPAPERSOURCE 


The SELECTPAPERSOURCE printer escape has been superseded by the 
DeviceCapabilities function (using the DC_BINS value). SELECTPAPER- 
SOURCE is provided only for backward compatibility. 
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SETABORTPROC 


short Escape(/idc, SETABORTPROC, NULL, [pAbortFunc, NULL) 


Parameters 


Return Value 


Comments 


The SETABORTPROC printer escape is maintained for backwards compati- 
bility. Applications written for Windows 3.1 should use the SetA bortProc func- 
tion. 


This escape sets the Abort function for the print job. 


— Toallowa print job to be canceled during spooling, an application must set the 


Abort function before the print job is started with the STARTDOC escape. Print 
Manager calls the Abort function during spooling to allow the application to can- 
cel the print job or to take appropriate action for such errors as running out of disk 
space. If no Abort function is set, the print job will fail if there is not enough disk 
space for spooling. 


hdc 
HDC Identifies the device context. - 


lpAbortFunc 
FARPROC Points to the ree supplied Abort function. For details, see 
the following Comments section. 


The return value specifies the outcome of the escape. This value is greater than 
zero if the escape is successful. Otherwise, it is less than zero. 


The address passed as the IpAbortFunc parameter must be created by using the 
MakeProcInstance function. 


The callback function must use the Pascal calling convention and must be declared 


_ FAR. The Abort function must have the following form: 


short FAR PASCAL AbortF HIRE Ode) 
HDC hPr; 
short code; 


AbortF unc is a placeholder for the application-supplied function name. The actual — 


‘name must be exported by including it in an EXPORTS statement in the module- 


definition (.DEF) file for the application. 
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Following are the parameters in the Abort function: 


hPr | 
Identifies the device context. 


code 
Specifies whether an error has occurred. This parameter is zero if no error has _ 
occurred. It is SP_OUTOFDISK if Print Manager is currently out of disk space 
and more disk space will become available if the application waits. 


If code is SP_LOUTOFDISK, the application does not have to abort the print 


job. If it does not abort the print job, it must yield to Print poeaee by calling 
the PeekMessage or GetMessage function. 


Return Value The return value should be nonzero if the print job is to continue and zero if it is 
| | canceled. 


SETALLJUSTVALUES 


short Escape(idc, SETALLJUSTVALUES, sizeof(EXTTEXTDATA), [pinData, NULL) 


The SETALLJUSTVALUES printer escape is not recommended. Applications 
should use the ExtTextOut function instead of this escape. This escape sets all of 
the text-justification values that are used for text output in Windows 3.0 and 
earlier. 


Text justification is the process of inserting extra pixels among break characters in 
a line of text. The space character is normally used as a break character. 


Parameters _ hdc 
HDC Identifies the device context. 


[pInData | 

~ EXTTEXTDATA FAR * Points to an EXTTEXTDATA structure that de- 
fines the text-justification values. For more information about this structure, see 
the Comments section. 


Return Value The return value specifies the outcome of the escape. This value is 1 if the escape 
is successful. Otherwise, it is zero. 


496 SETALLJUSTVALUES 


Comments 


The [pInData parameter points to an EXTTEXTDATA structure that describes 
the text-justification values used for text output. The EXTTEXTDATA structure 
has the following form: 


typedef struct { 
short nSize; 
LPALLJUSTREC IpInData; 
LPFONTINFO IpFont; 
LPTEXTXFORM 1pXForm; 
LPDRAWMODE 1pDrawMode; 
} EXTTEXTDATA; 


This structure contains a JUST_ VALUE_STRUCT structure that has the follow- 
ing form: | 


typedef struct { 
short nCharExtra; 
WORD cch; 
short nBreakExtra; 
WORD nBreakCount; 
} JUST_VALUE_STRUCT; 


Following are the members of JUST_ VALUE_STRUCT structure: 


nCharExtra | | 
Specifies the total extra space, in font units, that must be distributed over cch 
characters. 


cch 
Specifies the number of characters over which the nCharExtra member is dis- 
tributed. 


nBreakExtra : 
Specifies the total extra space, in font units, that is distributed over nBreak- 
Count characters. 


nBreakCount | 
Specifies the number of break characters over which the nBreakExtra member 
is distributed. 


The units used for the nCharExtra and nBreakExtra members are the font units 
of the device and are dependent on whether relative character widths were enabled 
with the ENABLERELATIVEWIDTHS escape. 


The values set with this escape apply to subsequent calls to the TextOut function. | 
The driver stops distributing the extra space specified in the nCharExtra member 
when it has output the number of characters specified in the nCharCount 
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member. Likewise, it stops distributing the space specified by the nBreakExtra 
member when it has output the number of characters. specified by the nBreak- 
Count member. A call on the same string to the GetTextExtent function made 
immediately after the call to the TextOut function will be processed in the same 
manner. 


To reenable justification with the SetTextJustification and SetTextCharacterEx- 
tra functions, an application should call the SETALLJ USTVALUES escape and 
set the nCharExtra and nBreakExtra members to zero. 


SET_ARC_DIRECTION 
short paneer SET_ARC_ DIRECTION, sizeof(int), [pDirection, NULL) 


The SET_ ARC_ DIRECTION printer escape specifies the direction in which 
elliptical arcs are drawn using the graphics device interface (GDI) Arc function. 


By Anenin, elliptical arcs are drawn counterclockwise by GDI. This escape 
lets an application draw paths containing arcs drawn clockwise. 


Parameters hdc 
HDC Identifies the device context. 
lpDirection 


LPINT Points to a short integer specifyinis'th the arc direction. It can be one of 
the following values: 


COUNTERCLOCKWISE (0) 
CLOCKWISE (1) 
Return Value _. The return value is the previous arc direction. 
Comments ‘This escape maps to PostScript language elements and is intended for PostScript 


line devices. 
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SET_BACKGROUND_COLOR 


short Escape(idc, SET. BACKGROUND_ COLOR, nCount, IpNewColor, lpOldColor) 


Parameters 


Return Value 


Comments 


The SET_ BACKGROUND_ COLOR printer escape sets and retrieves the cur- 
rent background color for the device. 


The background color is the color of the screen surface before an application 
draws anything on the device. This escape is particularly useful for color printers 
and film recorders. 7 


This escape should be sent before the application draws anything on the current 
page. 


hdc 
HDC Identifies the device context. 


nCount | 
int Specifies the number of bytes pointed to by the JpNewColor parameter. 


lpNewColor 
LPDWORD Points to a 32-bit integer specifying the desired background color. 
This parameter can be NULL if the On is merely retrieving the current 
background color. 


[pOldColor 
LPDWORD Points to a 32-bit integer that receives the previous background 
color. This parameter can be NULL if the pappneanion does not use the previous 
background color. 


The return value is nonzero if the escape is Se This value is zero if it is un- 
successful. 


The default background color is white. 


The background color is reset to the default ditee the device driver receives an 
ENDDOC or ABORTDOC escape. | 
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SET_BOUNDS 


short Escape(hdc, SET_BOUNDS, sizeof(RECT), jpInData, NULL) 


Parameters 


Return Value 


Comments 


The SET_BOUNDS printer escape sets the bounding rectangie for the picture 
being produced by the device driver supporting the given device context. This 
escape is used when creating images in a file format such as Encapsulated Post- 
Script (EPS) and Hewlett-Packard Graphics Language (HPGL) for which there is 
a device driver. 


hdc 
HDC Identifies the device context. 


lpInData 
LPRECT Points to a RECT structure that specifies in device eseiainntes a 
rectangle that bounds the image to be output. 


The return value is nonzero if the escape was successful. Otherwise, it is zero. — 


An application should issue this escape before each page in the image. For single- 
page images, this escape should be issued immediately before the STARTDOC 


escape. | wa 


When an application uses coordinate-transformation escapes, device drivers may 


_ not perform bounding box calculations correctly. When an application uses the — 


SET_BOUNDS escape, the driver does not have to calculate the bounding box. 


Applications should always use this escape to ensure support for the Encapsulated 
PostScript (EPS) printing capabilities. 


SET CLIP BOX 


short Escape(hdc, SET_CLIP_ BOX, sizeof(RECT), [pClipBox, (LPSTR) NULL) 


The SET_CLIP_BOX printer escape sets the clipping rectangle or restores the 
previous clipping rectangle. This escape is implemented by printer drivers that use 
the coordinate-transformation escapes TRANSFORM __ oi SAVE_CTM, and 
RESTORE_CTM. 7 
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Parameters 


Return Value. 


Comments 


When an application calls a graphics device interface (GDI) output function, GDI 
calculates a clipping rectangle bounding the primitive and passes both the primi- 
tive and the clipping rectangle to the printer driver. The printer driver is expected 
to clip the primitive to the specified bounding rectangle. However, when an appli- 
cation uses the coordinate-transformation escapes, the clipping rectangle calcu- 
lated by GDI is usually invalid. An application can use the SET_ CLIP_ BOX 
escape to specify the correct clipping rectangle when coordinate transformations 
are used. | 


hdc 
HDC Identifies the device context. 

[pClipBox 
LPRECT Points to a RECT structure containing the bounding rectangle of the 
clipping region. If JpClipBox is not NULL, the previous clipping rectangle is 
saved and the current clipping rectangle is set to the specified bounds. If 
IpClipBox is NULL, the previous clipping rectangle is restored. 


The return value is nonzero if the clipping rectangle was properly set. Otherwise, 
it is Zero. 


This escape is used only by PostScript printer drivers. 


SETCOLORTABLE 


short Escape(idc, SETCOLORTABLE, sizeof(COLORTABLE_STRUCT), /pinData, lpColor) 


Parameters 


The SETCOLORTABLE printer escape sets an RGB color-table entry. If the 
device cannot supply the exact color, the function sets the entry to the closest 
possible approximation of the color. 


hdc | 
HDC Identifies the device context. 


lpInData 
COLORTABLE_STRUCT FAR * Points to a structure that contains the 
index and RGB value of the color-table entry. For more information about the 
COLORTABLE_STRUCT structure, see the following Comments section. 


iColbr 
LPDWORD Points to the fai integer that is to receive the RGB color value 
selected by the device driver to represent the requested color value. 


Return Value 


Comments 


SETCOLORTABLE 001 


The return value specifies the outcome of the escape. This value is positive if the 
escape 1S successtul. Otherwise, it is negative. : 


The COLORTABLE_ STRUCT structure has the following form: 


struct COLORTABLE_STRUCT { 
WORD = Index; 
_ DWORD rgb; 
Tees 


Following are the members of the COLORTABLE_ STRUCT structure: 


Index 


Specifies the color-table index. Color-table entries start at zero for the first 
entry. 


rgb 
Specifies the desired RGB color value. 


The color table for a device is a shared resource; changing the system display , 
color for one window changes it for all windows. Only application developers who 
have a thorough knowledge of the display driver should use this escape. 


The SETCOLORTABLE escape has no effect on devices with fixed color tables. | 


This escape is intended for use by both printer and display drivers. However, the 
EGA and VGA color drivers do not support it. 


This escape changes the palette used by the display driver. However, because the 
color-mapping algorithms for the driver will probably no longer work with a differ- 
ent palette, an extension has been added to this function. 


If the color index pointed to by the /pInData parameter is OXFFFF, the driver is to 
leave all color-mapping functionality to the calling application. The application 
must use the proper color-mapping algorithm and take responsibility for passing 
the correctly mapped physical color to the driver (instead of the logical RGB 


color) in such device-driver functions as RealizeObject and ColorInfo. 


For example, if the device supports 256 colors with palette indexes of 0 through 
255, an application determines which index contains the color that it wants to use 
in a certain brush. It then passes this index in the low-order byte of the double- 
word logical color passed to the RealizeObject device-driver function. The driver 


uses this color exactly as passed instead of performing its usual color-mapping al- 


gorithm. If the application wants to reactivate the driver’s color-mapping algo- — 
rithm (that is, if it restores the original palette when switching from its window 


context), then the color index pointed to by /pInData should be OXFFFE. 
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SETCOPYCOUNT 


short Escape(hdc, SETCOPYCOUNT, sizeof(int), JpNumCopies, lpActualCopies) 


Parameters 


Return Value 


The SETCOPYCOUNT printer escape is maintained for backwards compati- 
bility. Applications written for Windows 3.1 should use the ExtDeviceMode func- 


tion. 


This escape specifies the number of uncollated copies of each page that the printer 
is to print. 


hdc 
HDC Identifies the device context. 


lpNumCopies 
LPINT Points to a short integer that contains the number of uncollated copies 
to be printed. 


lpActualCopies 
LPINT Points to a short integer that will receive the number of copies to be 
printed. This may be less than the number requested if the requested number is 
greater than the maximum copy count for the device. 


The return value specifies the outcome of the escape. It is 1 if the escape is 
successful and zero if the escape is not successful. The return value is zero if the 
escape is not implemented. 


SETKERNTRACK 


short Escape(hdc, SETKERNTRACK, sizeof(int), [pNewTrack, lpOldTrack) 


The SETKERNTRACK printer escape specifies which kerning track to use for 
drivers that support automatic track kerning. A kerning track of zero disables auto- 


matic track kerning. 


When track kerning i is enabled, the driver will automatically kern all characters 
according to the specified track. The driver will reflect this kerning both on the 
printer and in GetTextExtent function calls. 


Parameters 


Return Value 


Comments 


SETLINECAP 


SETLINECAP 903 


hdc 


HDC Identifies the device context. 


lpNewTrack 
LPINT Points to a short integer that specifies the kerning track to use. A value 
of zero disables this feature. Values in the range 1 through the value of the 
etmKernTracks member correspond to positions in the track-kerning table 
(using 1 as the first item in the table). For more information, see the description 
of the EXTTEXTMETRIC structure provided in the description of the 
GETEXTENDEDTEXTMETRICS escape earlier in this chapter. 


[pOldTrack 
LPINT Points to a short integer that will receive the previous kerning track. 


The return value erties the outcome of the escape. It is il if the escape 1S 
successful and zero if the escape is not successful or not implemented. 


Automatic track kerning i is disabled by default. 


A save does not have to support the SETKERNTRACK escape just pease it 
supplies the track-kerning table to the application by using the GETTRACK- 
KERNTABLE escape. In a case where GETTRACKKERNTABLE is sup- 
ported but the SETKERNTRACK escape is not, the application must properly 
space the characters on ais a a device. 


short Escape(hdc, SETLINECAP, sizeof(int), [p>NewCap, IpOldCap) 


— The SETLINECAP printer escape sets the line end cap. 


A line end cap is that portion of a line segment that appears on either end of the 
segment. The cap may be square or circular. It can extend past or remain flush 
with the specified segment endpoints. 


004 SETLINEJOIN 


Parameters 


Return Value 


Comments 


hdc 
HDC Identifies the device context. 


lpNewCap , 
LPINT Points to a short integer that specifies the end-cap type. Following are 
the possible values and their meanings: 


Value Meaning 
—] Line segments are drawn by using the default graphics device interface 
. (GDJD end cap. 

0 Line segments are drawn with a squared end point that does not project 


past the specified segment length. 


1 Line segments are drawn with a rounded end point; the diameter of this 
semicircular arc is equal to the line width. 


2 Line segments are drawn with a squared end point that projects past the 
specified segment length. The projection is equal to half the line width. 


lpOldCap | | 
LPINT Points to a short integer that specifies the previous end-cap setting. 


The return value specifies the outcome of the escape. It is positive if the escape is 
successful. Otherwise, it is negative. 


This escape is used only by PostScript printer drivers. 


The interpretation of this escape varies with page-description languages (PDLs). 
For its exact meaning, consult the PDL documentation. 


This escape is also known as SETENDCAP. 


SETLINEJOIN 


short Escape(hdc, SETLINEJOIN, sizeof(int), [pNewJoin, lpOldJoin) 


Parameters 


The SETLINEJOIN printer escape specifies how a device driver will join two in- 
tersecting line segments. The intersection can form a rounded, squared, or mitered 
corner. 


> 


hdc 


HDC Identifies the device context. 


lpNewJoin | 
LPINT Points to a short integer that specifies the type of intersection. Follow- 
ing are the possible values and their meanings: 


~ SETMITERLIMIT 905 


Value —-~ Meaning 
—] Line segments are joined by using the default graphics device interface 
(GDI) setting. 

0 Line segments are joined with a mitered corner; the outer edges of the 
lines extend until they meet at an angle. This is referred to as a miter 
join. 

1 Line segments are joined with a rounded corner; a semicircular arc with 


a diameter equal to the line width is drawn around the point where the 
lines meet. This is referred to as a round join. | 


Z Line segments are joined with a squared end point; the outer edges of 
the lines are not extended. This is referred to as a bevel join. 


lpOldJoin | | 
LPINT Points to a short integer that specifies the previous line join setting. 


Return Value The return value specifies the outcome of the escape. It is Spee if the escape is 
successful. Otherwise, it is negative. 


Comments This escape is used only by PostScript printer drivers. 


The interpretation of this escape varies with page-description languages (PDLs). 
For its exact meaning, consult the PDL documentation. 


If an application specifies a miter join but the angle of intersection is too small, the 
device driver ignores the miter setting and uses a bevel join instead. 


SETMITERLIMIT 


short Escape(idc, SETMITERLIMIT, sizeof(int), ipNewMiter, lpOldMiter) 


The SETMITERLIMIT printer escape sets the miter limit for a device. The miter 
limit controls the angle at which a device driver replaces a miter join with a bevel 
join. 


Parameters hdc 
HDC Identifies the device context. 


906 SET_POLY_MODE 


Return Value 


- Comments 


[pNewMiter 
LPINT Points to a short integer that specifies the desired miter limit. Only 
values greater than or equal to —1 are valid. If the value is —1, the driver will 
use the default graphics device interface (GDI) miter limit. 


| lpOldMiter 


LPINT Points to a short integer that specifies the previous miter-limit setting. 


The return value specifies the outcome of the escape. This value is positive if the 
escape is successful. Otherwise, it is negative. 


This escape is used only by PostScript printer drivers. 
The miter limit is defined as follows: 

miter length / line width = 1/ sin(x/2)_ 

where x is the angle of the line join, in radians. 


The interpretation of this escape varies with page-description languages (PDLs). 
For its exact crane consult the PDL documentation. 


SET_POLY_MODE 


short Escape(idc, SET_ POLY_ MODE, sizeof(int), lpMode, NULL) 


Parameters 


The SET_POLY_MODE printer escape sets the poly mode for the device driver. 
The poly mode is a state variable indicating how to interpret calls to graphics | 
device interface (GDI) Polygon and Polyline functions. 


The SET_POLY_ MODE escape enables a device driver to draw shapes (such as 
Bezier curves) not directly supported by GDI. This permits applications that draw 
complex curves to send the curve description directly to a device without having 


to simulate the curve as a polygon with a large number of points. 


hdc 
HDC Identifies the device context. 


lpMode | 
LPINT Points to a short integer specifying the desired poly mode. The poly 
mode is a state variable indicating how points in Polygon or Polyline function 
calls should be interpreted. Device drivers are not required to support all. 
possible modes. A device driver returns zero if it does not support the specified 
mode. The /pMode parameter may be one of the following values: 


Value 


PM_POLYLINE (1) 


PM_BEZIER (2) 


PM_POLYLINESEGMENT (3) 


PM_POLYSCANLINE (4) 


SET_POLY_MODE 007 


Meaning 
Points define a conventional polygon or poly- 
line. 


Points define a sequence of aos Bezier 
spline curves. The first curve passes through 
the first four points, with the first and fourth 
points as endpoints and the second and third 
points as control points. Each subsequent curve 
in the sequence has the endpoint of the pre- 
vious curve as its start point, the next two 
points as control points, and the third as its 
endpoint. | 
The last curve in the sequence is permitted to 
have fewer than four points. If the curve has 
only one point, it is considered a point. If it has 
two points, it is a line segment. If it has three 
points, it is a parabola defined by drawing a 
Bezier curve with the first and third points as 
endpoints and the two control points equal to 
the second point. 


Points specify a list of coordinate pairs. Line 
segments are drawn connecting each succes- 
sive pair of points. ) 
Points specify a list of coordinate pairs. Line 
segments are drawn connecting each succes- 
sive pair of points. Each line segment is a nomi- 
nal-width line drawn with the current brush. 
Each line segment must be strictly vertical or 
horizontal, and scan lines must be passed in 
strictly increasing or decreasing order. This 
mode is only used for polygon calls. 


Return Value The return value is the previous poly mode. If the return value is zero, the device 


driver did not handle the request. 


Comments This escape is used only by PostScript printer drivers. 


An application should issue the SET_POLY_ MODE escape before it draws a 
complex curve. It should then call the Polyline or Polygon function with the 
desired control points defining the curve. After drawing the curve, the application 
should reset the driver to its previous state by issuing the SET_POLY_MODE 


escape. 


Polyline calls draw using the sais selected pen. 


908 SET_SCREEN_ANGLE 


Polygon calls draw using the currently selected pen and brush. If the start point 
and endpoint are not equal, a line is drawn from the start point to the endpoint 
before the polygon (or curve) is filled. 


_ GDI treats Polygon calls using PM_POLYLINESEGMENT mode onan the 


same as Polyline calls. 


Four points define a Bezier curve. GDI generates the curve by connecting the first 
and second, second and third, and third and fourth points. GDI then connects the 
midpoints of these consecutive line segments. Finally, GDI connects the midpoints 
of the lines connecting the midpoints, and so forth. 


The line segments drawn in this way converge to a curve defined by the following 
parametric equations, expressed as a function of the independent variable t. 


X(t) = (1-0) 3 x, + 3(1-t) 2 tx, + 3(1-Ot 7? x, +t? x, 
Y( = (1-0) 3 y, + 3(1-0) 2 ty, + 3(1-Ot? y, +t? y, 


The points (x,, y,), (X25 V2)» (%3» 3) and (x,, y,) are the control points defining the 
curve. The independent variable t varies from 0 to 1. 


Primitive types other than PM_BEZIER and PM_POLYLINESEGMENT may be 
added to this escape in the future. Applications should check the return value from 
this escape to determine whether the driver supports the specified poly mode. 


SET SCREEN ANGLE 


short Escape(/idc, SET_ SCREEN_ANGLE, sizeof(int), JpAngle, NULL) 


Parameters 


Return Value 


The SET_SCREEN_ ANGLE printer escape sets the current screen angle to the 
desired angle and enables an application to simulate the tilting of a photographic 
mask in producing a color separation for a particular primary. 


hdc 
HDC Identifies the device context. 

lpAngle 
LPINT Points to a short integer specifying the desired screen angle in tenths of 
a degree. The angle is measured counterclockwise. 


The return value is the previous screen angle. 


Comments 


SET_ SPREAD 909 


Four-color process separation is the process of separating the colors comprising an 
image into four component primaries: cyan, magenta, yellow, and black. The 
image is then reproduced by overprinting each primary. 


In traditional four-color process printing, half-tone images for each of the four pri- — 
maries are photographed against a mask tilted to a particular angle. Tilting the 
mask in this manner minimizes unwanted moiré patterns caused by overprinting 
two or more colors. 


The device driver defines the default screen angle. 


SET_ SPREAD 


short Escape(hdc, SET_SPREAD, sizeof(int), [pSpread, NULL) 


Parameters 


Return Value 


Comments 


The SET_SPREAD printer escape sets the amount that nonwhite primitives are 
expanded for a given device to provide a slight overlap between primitives to com- 
pensate for imperfections in the reproduction process. . 


Spot color separation is the process of separating an image into each distinct color 
used in the image. The image is pC Oguce by overprinting each successive color 
in the image. . 


When reproducing a spot-separated image, the printing equipment must be cali- 
brated to align each page exactly on each pass. However, differences in tempera- 
ture, humidity, and so forth between passes often cause images to align 
imperfectly on subsequent passes. For this reason, lines in spot separations are 
often widened (spread) slightly to make up for problems in registering subsequent 
passes through the printer. This process is called trapping. The SET SPREAD 
escape implements this process. 


hdc | 
HDC Identifies the device context. 


lpSpread 
LPINT Points to a short integer that ae the amount, in pixels, by which 
all nonwhite primitives are to be expanded. 


The return value is the previous spread value. 


The default spread is zero. 


The current spread applies to all bordered primitives (whether or not the border is 
visible) and text. 


910 STARTDOC 


STARTDOC 


short aoe STARTDOC, nCount, IpDocName, NULL) 


Parameters 


Return Value 


Comments 


The STARTDOC printer escape is maintained for backwards compatibility. 
Applications written for Windows 3.1 should use the StartDoc function. 


This escape informs the device driver that a new print job is starting and that all 
subsequent NEWFRAME escape calls should be spooled under the same job until 
an ENDDOC escape call occurs. This ensures that documents longer than one 
page will not be interspersed with other jobs. 


hdc 
HDC Identifies the device context. 


nCount 
short Specifies the number of oes in the string pointed to by the 
lpDocName parameter. 


lpDocName | 
LPSTR Points to a null-terminated string that specifies the name of the docu- 
ment. The document name is displayed in the Print Manager window. The maxi- 
mum length of this string is 31 characters plus the terminating null character. 


The return value specifies the outcome of the escape. It is —1 if an error such as in- 
sufficient memory or an invalid port specification occurs. Otherwise, it is positive. 


Following is the correct sequence of events in a printing operation: 


1. Create the device context. 


2. Set the Abort function to keep out- a errors $ from terminating a print- 
ing operation. : 


An Abort procedure that handles these errors must be set by using the 
SETABORTPROC escape. 


3. Begin the printing operation with the STARTDOC escape. 


4. Begin each new page with the NEWFRAME escape or each new band with the 


NEXTBAND escape. 
5. End the printing operation with the ENDDOC escape. 
6. Destroy the Cancel dialog box, if any. 
7. Free the procedure-instance address of the Abort function. 


TRANSFORM_CTM 911 


If an application encounters a printing error or a canceled print operation, it must 
not attempt to terminate the operation by using the Escape function with either the 
ENDDOC or ABORTDOC escape. Graphics device interface (GDI) automat- 
ically terminates the operation before returning the error value. 


The STARTDOC escape should not be used inside metafiles. 


STRETCHBLT 


See Also 


The STRETCHBLT printer escape is provided for backwards compatibility. 
Applications should use the StretchBlt function instead of this escape. 


StretchBlt 


-TRANSFORM_CTM 


short Escape(hdc, TRANSFORM_CTM, 36, [pMatrix, NULL) 


- Parameters 


The TRANSFORM_ CTM printer escape modifies the current transformation 
matrix. The current transformation matrix controls the manner in which coordi- 
nates are translated, rotated, and scaled by the device. By using matrices, you can © 
combine these operations in any order to produce the desired mapping for a partic- 
ular picture. 


The new current transformation matrix will contain the product of the matrix refer- 
enced by the /pMatrix parameter and the previous current transformation matrix 
(CTM =M * CTM). 


hdc 
HDC Identifies the device context. 


[pMatrix 
LPSTR Points to a 3-by-3 array of 32-bit integer values specifying the new 
transformation matrix. Entries in the matrix are scaled to represent fixed-point 
real numbers. Each matrix entry is scaled by 65,536. The high-order word of 
the entry contains the whole integer portion, and the low- order word contains 
the fractional portion. | 7 


912 TRANSFORM_CTM 


Return Value The return value is nonzero if the escape was successful and zero if it was un- 


successful. | 7 | 
Comments This escape is used only by PostScript printer drivers. 


When an application modifies the current transformation matrix, it must specify 
the clipping rectangle by issuing the SET_ CLIP_ BOX escape. 


Applications should not make any assumptions about the initial value of the cur- 
rent transformation matrix. 


Dynamic Data Exchange 
Transactions 


— Chapter § 
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XTYP_ADVDATA 


~ Parameters 


Return Value 


Comments 


See Also | 


XTYP_ADVDATA 915 


The Dynamic Data Exchange Management Library (DDEML) notifies an applica- 
tion of dynamic data exchange (DDE) activity that affects the application by send- 
ing transactions to the application’s DDE callback function. A transaction is 
similar to a message—it is a named constant accompanied by other parameters 
that contain additional information about the transaction. 


This chapter lists the DDE transactions in alphabetic order. 


#Finclude <ddeml] .h>. 


XTYP_ADVDATA | 
hszTlopic = hszl; /* handle of topic-name string */ 
hszItem = hsz2; /* handle of item-name string */ 
hDataAdvise = hData; /* handle of the advise data * / 


A client’s DDE callback function can receive this transaction after the client has 
established an advise loop with a server. This transaction informs the client that 
the value of the data item has changed. 


hszTopic | 
Value of hszl. Identifies the eae name. 


hszItem 


Value of hsz2. Identifies the item name. 


hDataAdvise 
Value of hData. Identifies the data associated with the topic/item name pair. If 
the client specified the XTYPF_NODATA flag when it requested the advise 
loop, this parameter is NULL. 


A DDE callback function should return DDE_FACK if it processes this 
transaction, DDE_FBUSY if it is too busy to process this transaction, or 
DDE_FNOTPROCESSED if it denies this transaction. 


An application need not free the data handle obtained during this transaction. If the 


application needs to process the data after the callback function returns, however, 
it must copy the data associated with the data handle. An appieanen can use the 
DdeGetData function to copy the data. 


DdeClientTransaction, DdePostAdvise 


016 XTYP_ADVREQ 


XTYP_ADVREQ 


Parameters 


Return Value 


Comments 


See Also 


#Hinclude <ddeml].h> 


XTYP_ADVREQ 


hszTopic = hszl; /* handle of topic-name string —— */ 
hszItem = hsz2; /* handle of item-name string * / 
cAdvReq = LOWORD(dwDatal); /* count of remaining transactions */ 


The system sends this transaction to a server after the server calls the DdePost- 
Advise function. This transaction informs the server that an advise transaction is 
outstanding on the specified topic/item name pair and that data corresponding to 
the topic/item name pair has changed. 


hszTopic 
_ Value of hsz1. Identifies the topic name. 


hszltem | 
Value of hsz2. Identifies the item name that has changed. 


cAdvReq | 
Value of the low-order word of dwData1. Specifies the count of 
XTYP_ADVREQ transactions that remain to be processed on the same 
topic/itemn/format name set, within the context of the current call to the 
DdePostAdvise function. If the current XTYP_ADVREQ transaction is the 
last one, the count is zero. A server can use this count to determine whether 
to create an HDATA_APPOWNED data handle for the advise data. 


If the DDEML issued the XTYP_ADVREQ transaction because of a late- 
arriving DDE_FACK transaction flag from a client, the low-order word is set to 
CADV_LATEACK. The DDE_FACK transaction flag arrives late when a serv- 
er is sending information faster than a client can process it. 


The server should call the DdeCreateDataHandle function to create a data handle | 
that identifies the changed data and then should return the handle. If the server is 
unable to complete the transaction, it should return NULL. 


A server cannot block this transaction type: the CBR_BLOCK return value is ig- 
nored. 


DdeCreateDataHandle, Ddelnitialize, DdePostAdvise 


XTYP_ADVSTART 517 


XTYP_ADVSTART oe a 


#Hinclude <ddem].h> 


XTYP_ADVSTART 
hszTopic = hszl; /* handle of topic-name string */ 
hszItem = hsz2; /* handle of item-name string */ 


A server’s DDE callback function receives this transaction when a client specifies 
XTYP_ADVSTART for the w7ype parameter of the DdeClientTransaction func- 
tion. A client uses this transaction to establish an advise loop with a server. 


Parameters hszTopic 
- Value of hsz/. Identifies the topic name. 


hszItem | 
Value of hsz2. Identifies the item name. 


Return Value — To allow an advise loop on the specified topic/item name pair, a server’s DDE call- 
back function should return a nonzero value. To deny the advise loop, it should re- 
turn zero. If the callback function returns a nonzero value, any subsequent call by 
the server to the DdePostAdvise function on the same topic/item name pair will 
cause the system to send a XTYP_ADVREQ transaction to the server. 


Comments If a client requests an advise loop on a topic/item/format name set for which an ad- 

a vise loop is already established, the DDEML does not create a duplicate advise | 
loop. Instead, the DDEML alters the advise loop flags (XTYPF_ACKREQ and 
XTYPF_NODATA) to match the latest request. | 


If the server application specified the CBF_ FAIL _ADVISES flag 1 in the 
Ddelnitialize function, this transaction is filtered. . 


See Also | DdeClientTransaction, Ddelnitialize, DdePostAdvise | | 


518 XTYP_ADVSTOP 


XTYP_ADVSTOP Ae | tain 
—dFinclude <ddeml .h> 


XTYP_ADVSTOP 
hszTopic = hszl; /* handle of topic-name string */ 
hszItem = hsz2; /* handle of item-name string */ 


A server’s DDE callback function receives this transaction when a client specifies 
XTYP_ADVSTOP for the wType parameter of the DdeClientTransaction func- 
tion. A client uses this transaction to end an advise loop with a server. 


Parameters hszTopic | 
3 _ Value of hsz/. Identifies the topic name.. 
hszltem | 
Value of hsz2. Identifies the item name. 
Return Value This transaction does not return a value. 
Comments | If the server application specified the CBF_FAIL_ADVISES flag in the 


Ddelnitialize function, this transaction is filtered. 


See Also DdeClientTransaction, Ddelnitialize, DdePostAdvise 


-XTYP_CONNECT — rsa) 


d#Finclude <ddeml .h> 


XTYP_CONNECT 


hszTopic = hszl; /* handle of topic-name string * / 
hszService = hsz2; /* handle of service-name string a / 
pec = (CONVCONTEXT FAR *)dwDatal; /* address of CONVCONTEXT structure */ 


fSameInst = (BOOL) dwData2; /* same instance flag ry ae 


A server’s DDE callback function receives this transaction when a client specifies 
a service name that the server supports and a topic name that is not set to NULL in 
a call to the DdeConnect function. 


Parameters hszTopic : 
Value of hsz/. Identifies the topic name. 


hszService 
Value of hsz2. Identifies the service name. 


Return Value 


Comments 


See Also 


XTYP_CONNECT_ CONFIRM 


_ dFinclude <ddem! . n> 


Parameters 


XTYP_CONNECT_CONFIRM 919 


pec 
Value of dwDatal. Points toa CONVCONTEXT data structure that contains 
context information for the conversation. If the client is not a DDEML applica- 
tion, this parameter should be set to zero. 


fSamelnst 
_ Value of dwData2. Specifies whether the client is the same application instance 
as the server. If this parameter is TRUE, the client is the same instance; if this 
parameter is FALSE, the client is a different instance. 


To allow the client to establish a conversation on the specified service/topic name 
pair, a server’s DDE callback function should return a nonzero value. To deny the 
conversation, it should return zero. If the callback function returns a nonzero value 
and a conversation is successfully established, the system passes the conversation 
handle to the server by issuing an XTYP_CONNECT_CONFIRM transaction 

to the server’s DDE callback function (unless the server specified the 
CBF_FAIL_CONNECT_ CONFIRMS flag in the Ddelnitialize function). 


If the server application specified the CBF_FAIL_CONNECTIONS Hag u in the 
Ddelnitialize function, this transaction is filtered. 


A server cannot block this transaction type; the CBR_BLOCK return vee 1S Is: 


nored. 


DdeConnect Ddelnitialize 


XTYP_CONNECT_ CONFIRM 


hszTopic = hszl;. os /* handle of topic-name string ~ */ 
hszService = hsz2; /* handle of service-name string */ 
fSameInst = (BOOL) dwData2 ; /* same instance flag. vf 


_A server’s DDE callback function receives this transaction to conten that a con-— 
-versation has been established with a client and to provide the server with the con- 


versation handle. The system sends this transaction as a result of a previous 
pare Sik or XTYP_WILDCONNECT transaction. 


hszTopic 
Value of hszl. Identifies the topic name on which the conversation has been 
established. © 


920 XTYP_ DISCONNECT — 


Return Value 


Comments 


See Also 


XTYP_ DISCONNECT 


Parameters 


Return Value 


Comments 


hszService | 
Value of hsz2. Identifies the service name on which the conversation has been 
established. | 


fSamelnst 
Value of dwData2. Specifies whether the client is the same application instance 
as the server. If this parameter is a nonzero value, the client is the same in- 
stance. If this parameter is zero, the client is a different instance. 


This transaction does not return a value. 


_ If the server application specified the CBF_FAIL_CON FIRMS flag in the 


Ddelnitialize function, this transaction is filtered. 


A server cannot block this transaction type; the CBR_ -BLOCK return value is ig- 
nored. 


paceanaee: DdeConnectList, Ddelnitialize 


#Hinclude <ddeml .h> 


XTYP_DISCONNECT 


fSameInst = (BOOL) dwData2; /* same instance flag */ 


An application’ s DDE callback function receives this transaction when the applica- 
tion’s partner in a conversation uses the DdeDisconnect function to terminate the 
conversation. : | 


fSamelnst 
Value of dwData2. Specifies whether the partners in the conversation are the 
same application instance. If this parameter is TRUE, the partners are the same 
instance. If this parameter is FALSE, the partners are different instances. 


This transaction does not return a value. 


If the application specified the CBF_SKIP_DISCON NECTS flag in the 
DdelInitialize function, this transaction is filtered. 


See Also 


XTYP_EXECUTE 021 


The application can obtain the status of the terminated conversation by calling the 
DdeQueryConvInfo function while processing this transaction. The conversation 
handle becomes invalid after the callback function returns. 


An application cannot block this transaction type; the CBR_BLOCK return value 
is ignored. 


DdeDisconnect, DdeQueryConvinfo 


XTYP_ ERROR as | a] 


Parameters 


Return Value 


Comments 


#Finclude <ddem].h> 


XTYP_ERROR : 
wErr = LOWORD(dwDatal); /* error value */. 


A DDE callback function receives this transaction when a critical error occurs. 


WwErr — | | 
Value of dwData1. Specifies the error value. Currently, only the 
~ DMLERR_LOW_MEMORY error value is supported. It means that memory 
is low—advise, poke, or execute data may be lost, or the system may fail. 


This transaction does not return a value. 
An application cannot block this transaction type; the CBR_BLOCK return value 


is ignored. The DDEML attempts to free memory by removing noncritical re- 
sources. An application that has blocked conversations should unblock them. 


XTYP_EXECUTE aa] 


#Hinclude <ddem1.h> 


XTYP_EXECUTE 
hszTopic = hszl; /* handle of the topic-name string */ 
hDataCmd = hData; /* handle of the command string * / 


A server’s DDE callback function receives this transaction when a client specifies 
XTYP_EXECUTE for the wType parameter of the DdeClientTransaction func- 
tion. A client uses this transaction to send a command string to the server. 


922 XTYP_ MONITOR 


Parameters 


Return Value 


Comments 


See Also 


XTYP_MONITOR 


Parameters 


hszTopic 
Value of hsz/. identities the topic name. 


hDataCmd 
Value of hData. Identifies the command string. 


A server’s DDE callback function should return DDE_FACK if it processes this 
transaction, DDE_FBUSY if it is too busy to process this transaction, or 
DDE_FNOTPROCESSED if it denies this transaction. 


If the server application specified the CBF_FAIL_EXECUTES flag in the 


Ddelnitialize function, this transaction is filtered. 


An application need not free the data handle obtained during this transaction. If the 
application needs to process the string after the callback function returns, however, 
the application must copy the command string associated with the data handle. An 
application can use the DdeGetData function to copy the data. 


DdeClientTransaction, Ddelnitialize 


#Hinclude <ddem].h> 


XTYP_MONITOR 
hDataEvent = hData; /* handle of event data */ 
fwEvent = dwData2; //* event flag */ 


- The DDE callback function of a DDE debugging application receives this transac- 


tion whenever a DDE event occurs in the system. An application can receive this 
transaction only if it specified the APPCLASS_MONITOR flag when it called the 
Ddelnitialize function. 


hDataEvent 
Value of hData. Identifies a global memory object that contains infonitiation 
about the DDE event. The application should use the DdeAccessData function 
to obtain a pointer to the object. 


JwEvent 
Value of dwData2. Specifies the DDE event. This parameter may be one of the 
following values: 


Value 


MF_CALLBACKS 
MF_CONV 
MF_ERRORS 


ME_HSZ, INFO 


MF_LINKS 


MF POSTMSGS 


MF_SENDMSGS _ 


Return Value 


See Also 


XTYP_ POKE 


#Hinclude <ddem1.h> 


XTYP_POKE 

hszTopic = hszl; 
hszIitem = hsz2; 
hDataPoke = hData; 


XTYP_POKE 


Meaning 


The system sent a transaction to a DDE callback function. 
The global memory object contains a MONCBSTRUCT 
structure that provides information about the transaction. 


A DDE conversation was established or terminated. The 
global memory object contains aMONCONVSTRUCT 
structure that provides information about the conversation. 


A DDE error occurred. The global memory object contains 
a MONERRSTRUCT structure that pores information 
about the error. 


A DDE application created or freed a string handle or 
incremented the use count of a string handle, or a string 
handle was freed as a result of a call to the DdeUninitialize 
function. The global memory object contains a 
MONHSZSTRUCT structure that provides infor- 

mation about the string handle. 


A DDE application started or ended an advise loop. The 
global memory object contains a MONLINKSTRUCT 
structure that provides information about the advise loop. 
The system or an application posted a DDE message. The 
global memory object contains aMONMSGSTRUCT 


‘structure that provides information about the message. 


The system or an application sent a DDE message. The 


- global memory object contains a MONMSGSTRUCT | 


structure that provides information about the message. 


The callback function should return zero if it processes this transaction. 


DdeAccessData, Ddelnitialize 


/* handle of topic-name string */ 
/* handle of item-name string */ 
/* handle of data for server * / 


523 


A server’s DDE callback function receives this transaction when a client specifies 
XTYP_POKE as the wT ype parameter of the DdeClientTransaction function. A | 
client uses this transaction to send unsolicited data to the server. 


524 XTYP_REGISTER 


Parameters hszTopic fag 
Value of hsz/. Identifies the topic name. 


hszltem | , 
Value of hsz2. Identifies the item name. 


hDataPoke | | 
Value of hData. Identifies the data that the client is sending to the server. 


Return Value A server’s DDE callback function should return DDE_FACK if it processes this 
transaction, DDE_FBUSY if it is too busy to process this transaction, or 
DDE_FNOTPROCESSED if it denies this transaction. 


Comments If the server application specified the CBF_FAIL_POKES flag in the 
Ddelnitialize function, this transaction is filtered. 


See Also DdeClientTransaction, DdelInitialize 


XTYP_REGISTER Be 


#Hinclude <ddeml.h> 


XTYP_REGISTER 
hszBaseServName = hsz1; /* handle of base service-name string * / 
hszInstServName = hsz2; /* handle of instance service-name string */ 


A DDE callback function receives this transaction type whenever a DDEML serv- 
er application uses the DdeNameService function to register a service name or 
whenever a non-DDEML application that supports the System topic is started. 


Parameters _ hszBaseServName 
Value of hsz/. Identifies the base service name being registered. | 


hszInstServName 
Value of hsz2. Identifies the instance-specific service name being registered. 


~ReturnValue | This transaction does not return a value. 


Comments If the application specified the CBF_SKIP_REGISTRATIONS flag in the 
Ddelnitialize function, this transaction is filtered. — 


An application cannot block this transaction type; the CBR_BLOCK return value © 
is ignored. = : | 


See Also 


XTYP_REQUEST 


Parameters 


Return Value 


Comments 


See Also 


XTYP_REQUEST 020 


An application should use the hszBaseServName parameter to add the service 
name to the list of servers available to the user. An application should use the 
hszInstServName parameter to identify which application instance has started. 


Ddelnitialize, DdeNameService 


d#Finclude <ddeml.h> 


XTYP_REQUEST i 
hszTopic = hszl; __ /* handle of topic-name string */ 
hszItem = hsz2; = /* handle of item-name string */ 


A DDE server callback function receives this transaction when a client specifies 
XTYP_REQUEST for the w7ype parameter of the DdeClientTransaction func- 
tion. A client uses this transaction to request data from a server. 


hszTopic 
Value of hszJ. Identifies the topic name. 


hszItem | 
Value of hsz2. Identifies the item name that has changed. 


The server should call the DdeCreateDataHandle function to create a data handle 
that identifies the changed data and then should return the handle. The server | 
should return NULL if it is unable to complete the transaction. If the server returns 
NULL, the client receives a DDE_FNOTPROCESSED acknowledgment flag. 


If the server application specified the CBF_FAIL_REQUESTS flag in the 


’ Ddelnitialize function, this transaction is filtered. 


If responding to this transaction requires lengthy processing, the server can return 
CBR_BLOCK to suspend future transactions on the current conversation and then 
process the transaction asynchronously. When the server has finished and the data 
is ready to pass to the client, the server can call the DdeEnableCallback function _ 
to resume the conversation. 


DdeClientTransaction, DdeCreateDataHandle, DdeEnableCallback, 
Ddelnitialize 
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XTYP_UNREGISTER — pa] 


#Hinclude <ddem1.h> 


XTYP_UNREGISTER 
hszBaseServName = hszl; /* handle of base service-name string * / 
hszInstServName = hsz2; /* handle of instance service-name string */ 


A DDE callback function receives this transaction type whenever a DDEML serv- 
er application uses the DdeNameService function to unregister a service name or 
whenever a non-DDEML application that supports the System topic is terminated. 


_ Parameters hszBaseServName 
Value of hsz/. Identifies the base service name being mueeieied 


hszInstServName 
Value of hsz2. Identifies the instance-specific service name being unregistered. 


Return Value This transaction does not return a value. 


Comments If the application specified the CBF_SKIP_REGISTRATIONS flag 1 in the 
Ddelnitialize function, this transaction is filtered. 


An application cannot block this transaction type; the CBR_BLOCK return value 
is ignored. 


An application should use the hszBaseServName parameter to remove the service 
name from the list of servers available to the user. An application should use the 
hszInstServName parameter to identify which application instance has terminated. 


See Also Ddelnitialize, DdeNameService 


XTYP_WILDCONNECT a ve: far 


_#include <ddem] .h> 


~ XTYP_WILDCONNECT 
hszTopic = hszl; /* handle of topic-name string x / 
hszService = hsz2; /* handle of service-name string oe / 
pec = (CONVCONTEXT FAR *)dwDatal; /* address of CONVCONTEXT structure * / 
fSameInst = (BOOL) dwData2; as same-instance flag * / 


Parameters 


Return Value 


Comments 


See Also 


XTYP_WILDCONNECT o27 


A server’s DDE callback function receives this transaction when a client specifies 
a service name that is set to NULL, a topic name that is set to NULL, or both in a 
call to the DdeConnect function. This transaction allows a client to establish a 
conversation on each of the server’s service/topic name pairs that matches the 
specified service name and topic name. 


hszTopic | 
Value of hsz1. Identifies the topic name. If this parameter is NULL, the client is 
requesting a conversation on all topic names that the server supports. 


hszService | 
Value of hsz2. Identifies the service name. If this parameter is NULL, the client 
is requesting a conversation on all service names that the server supports. 


pec 
Value of dwData1. Points to a CONVCONTEXT: data structure that contains 
context information for the conversation. If the client is not a DDEML applica- 
tion, this parameter is set toz Zero. 


fSamelnst 
Value of dwData2. Specifies whether the client is the same application instance 
as the server. If this parameter is TRUE, the client is same instance. If this 
parameter is FALSE, the client is a different instance. 


The server should return a data handle that identifies an array of HSZPAIR 


structures. The array should contain one structure for each service/topic 

name pair that matches the service/topic name pair requested by the client. 

The array must be terminated by a NULL string handle. The system sends the 
XTYP_CONNECT_CONFIRM transaction to the server to confirm each conversa- 
tion and to pass the conversation handles to the server. If the server specified the 
CBF_SKIP_CONNECT _CONFIRMS — in the DdelInitialize function, it cannot 
receive these confirmations. 


To refuse the XTYP ONES transaction, the server should return 
NULL. 


If the server apenas specified the CBF_ FAIL_ CONNECTIONS flag in the 


-Ddelnitialize function, this transaction is filtered. 


A server cannot block this transaction type; the CBR_BLOCK return code is ig- 
nored. — 


DdeConnect, Ddelnitialize 


528 XTYP_XACT_COMPLETE 


XTYP_XACT_COMPLETE 


Parameters 


Return Value 


Comments 


See Also 


d#Hinclude <ddeml].h> 


XTYP_XACT_COMPLETE 


hszTopic = hszl; /* handle of topic-name string */ 
hszItem = hsz2; /* handle of item-name string */ 
hDataXact = hData; /* handle of transaction data */ 
dwXactID = dwDatal; /* transaction identifier * / 
fwStatus = dwData2; /* status flag * / 


A DDE client callback function receives this transaction when an asynchronous 
transaction, initiated by a call to the DdeClientTransaction function, has con- 
cluded. 


hszTopic 
Value of hsz/. Identifies the topic name involved in the completed transaction. 


hszItem 
Value of hsz2. Identifies the item name involved in the completed transaction. 


hDataxXact 
Value of hData. Identifies the data involved in the completed transaction, if ap- 
plicable. If the transaction was successful but involved no data, this parameter 
is TRUE. If the transaction was unsuccessful, this parameter is NULL. 


dwXactID | | 
Value of dwData!. Contains the transaction identifier of the completed transac- . 
tion. 

JwStatus 
Value of dwData2. Contains any applicable DDE_ status flags in the low- order 
word. This provides support for applications dependent on DDE_APPSTATUS 
bits. It is recommended that applications no longer use these bits—future ver- 
sions of the DDEML may not support them. 


This transaction does not return a value. 


An application need not free the data handle obtained during this transaction. If the 
application needs to process the data after the callback function returns, however, 
the application must copy the data associated with the data handle. An application 
can use ee DdeGetData function to copy the data. 


DdeClientTransaction 


_ File Manager Events and Messages 


) Chapter T 
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FMEVENT_INITMENU 037 


File Manager communicates with a File Manager extension dynamic-link library 
(DLL) by sending events and menu commands to the DLL’s FMExtensionProc | 
function. While processing an event or command, the DLL can retrieve informa- 
tion from File Manager by sending File Manager messages using the Send- © 
Message function. This chapter provides complete descriptions of both the 

events and messages for File Manager in Microsoft Windows operating system, 
version 3.1 | 


7.1 File Manager Events 


This section lists File Manager events in alphabetic order. 


FMEVENT_INITMENU 


Parameters | 


Return Value 


Comments 


See Also 


The FMEVENT_INITMENU message is sent to an extension dynamic-link 
library (DLL) when the user selects the menu for the extension from File 
Manager’ s menu bar. The extension can use this notification to initialize menu 
items in the menu. : 


lParam | 
Specifies the menu handle in the high-order word. The low- der word speci- 
fies the delta value for the menu item. 


This message does not return a value. 


An extension receives this message only when the user selects the top-level menu. 
If the extension contains submenus, it must initialize them at the same time as the 
top-level menu. 


FMExtensionProc 


J32 FMEVENT_LOAD 


FMEVENT_LOAD 


The FMEVENT_LOAD message is sent to an extension dynamic- link library 
(DLL) when File Manager is loading the DLL. 


Parameters [Param 
Points to an FMS_ LOAD structure that specifies the menu-item delta value. 
An extension DLL should save the menu-item delta value and fill the other 
structure members with information about the extension. ne FMS_LOAD 
structure has the following form: 


dtinclude <wfext.h> 


typedef struct tagFMS_LOAD { / fms 1d * / 
DWORD dwSize; 
char szMenuName[MENU_TEXT_LEN]; 
HMENU hMenu; 
UINT wMenuDelta; 


} FMS_ LOAD; 
Return Value This message does not return a value. 
Comments An application should fill the dwSize, ssMenuName, and hMenu members. It 


should also save the value of the wMenuDelta member and use it to identify 
menu items when modifying the menu. For more information, see the description 
of the FMS_LOAD structure. 


See Also FMExtensionProc 


FMEVENT_SELCHANGE 


The FMEVENT_SELCHANGE message is sent to an extension dynamic-link 
library (DLL) when the user selects a filename in File Manager’ S directory win- 
dow or Search Results window. 


Parameters lParam 
Not used. 


Return Value This message does not return a value. 


Comments 


See Also 


FMEVENT_USER_REFRESH J33 


Changes in the tree half of the directory window do not produce this message. 


Because the user can change the selection many times, the extension DLL must re- 
turn promptly after processing this message to avoid slowing the selection process 
for the user. 


FMExtensionProc 


FMEVENT_ UNLOAD 


Parameters 


| Return Value 


Comments 


See Also 


The FMEVENT_UNLOAD message is sent to an extension a dynamic- link library 
(DLL) when File Manager is oe the DLL. 


lParam 
Not used. 


This message does not return a value. 


The hwnd and hMenu values passed with the FAEVENT_LOAD and | 
FMEVENT_INITMENU messages may not be valid at the time of this message. 


FMExtensionProc 


FMEVENT_ USER_REFRESH 


Parameters 


Return Value | 


See Also 


The FMEVENT_USER_ REFRESH message is sent to an extension dynamic- -link 
library (DLL) when the user invokes File Manager’s Refresh command in the Win- 
dow menu. The extension can use this notification to update. its menu. | 


lParam 
Not used. 


This message does not return a value. 


| FMExtensionProc 


934 FM_GETDRIVEINFO 


7. é File Manager Messages 


_ This section lists File Manager messages in alphabetic order. 


FM_GETDRIVEINFO 


A File Manager extension sends an FM_GETDRIVEINFO message to retrieve 
drive information from the active File Manager window. 


Parameters wParam 
Not used. 


lParam 
Points to an FMS_GETDRIVEINFO structure that receives drive informa- 
tion. The FMS_GETDRIVEINFO structure has the following form: 


d#Hinclude <wfext.h> 


typedef struct tagFMS_GETDRIVEINFO { /* fmsgdi */ 
DWORD. dwlotalSpace; 
DWORD dwFreeSpace; 
char szPath[260]; 
char szVolume[14]; 
char szShare[128]; 
} FMS_GETDRIVEINFO, FAR *LPFMS_ GETDRIVEINFO; 


Return Value The return value is always nonzero. 


See Also FMExtensionProc 


FM_ GETFILESEL 


A File Manager extension sends an FM_GETFILESEL message to retrieve infor- 
mation about a selected file from the active File Manager window (either the 
directory window or the Search Results window). 


Parameters 


Return Value — 


Comments - 


See Also 


FM_GETFILESELLFN 535 


wParam 
Specifies the zero- -based index of the selected file to retrieve. 


lParam | 
Points to an FMS_GETFILESEL structure that receives information about the 
selection. The FMS_GETFILESEL structure has the following form: 


d#Hinclude <wfext.h> 


typedef struct tagFMS_ GETFILESEL { /* fmsgfs */ 
UINT wlime; 
UINT wDate; 
DWORD dwSize; 
BYTE bAttr; 
char szName[l26@]; 
} FMS_GETFILESEL; 


The return value is the zero-based index of the selected file that was retrieved. 


An extension can use the FM_GETSELCOUNT message to obtain the count of 
selected files. 


The szName member of the FMS_ GETFILESEL structure consists of an OEM 
character string. Before displaying this string, an extension should use the Oem- 
ToAnsi function to convert the string to a Windows ANSI character string. If a 
string is to be passed to the file system (MS- DOS). an extension should not con- . 
vert it. , 


FMExtensionProc. FM_GETFILESELLEN, FM__ GETSELCOUNT, 
FM_GETSELCOUNTLEN, OemToAnsi 


FM_ GETFILESELLFN 


A File Manager extension sends an FM _GETFILESELLFN message to retrieve in- 


_ formation about a selected file from the active File Manager window (either the 
_ directory window or the Search Results window). The selected file can have a 


long filename. 


036 FM_GETFOCUS 


Parameters wParam 
Specifies the zero- based index of the selected file to retrieve. 


lParam 
Points to an FMS_GETFILESEL structure that receives information about the 
selection. The FMS_GETFILESEL structure has the following form: 


dFHinclude <wfext.h> 


typedef struct tagFMS_GETFILESEL { /* fmsgfs */ 
UINT wlime; 
UINT wDate; 
DWORD dwSize; 
BYTE bAttr; 
char szName[260]; 
} FMS_GETFILESEL; 


Return Value | The return value is the zero-based index of the selected file that was retrieved. 


Comments Only extensions that support long filenames (for example, network-aware exten- 
sions) should use this message. 


An extension can use the FA_GETSELCOUNT message to obtain the count of 
selected files. 


The szName member of the FMS_GETFILESEL structure consists of an OEM 
character string. Before displaying this string, an extension should use the Oem- 
ToAnsi function to convert the string to a Windows ANSI character string. If a 
string is to be passed to the file system (MS-DOS), an extension should not con- 
vert it. 


See Also | FMExtensionProc, FM_GETFILESEL, FM_GETSELCOUNT, 
FM_GETSELCOUNTLEN, OemToAnsi 


FM_GETFOCUS 


A File Manager extension sends a FM_GETFOCUS message to retrieve the type 
of the File Manager window that has the input focus. 


Parameters _ wParam 
| Not used. 


lParam 
Not used. 


Return Value 


FM_GETSELCOUNTLFN J3/ 


The return value indicates the type of File Manager window that has input focus. It 
can have one of the following values: 


Value Meaning | 
FMFOCUS_DIR | Directory portion of a directory window 
~ FMFOCUS_TREE Tree portion of a directory window 


FMFOCUS_DRIVES Drive bar of a directory window 
FMFOCUS_SEARCH Search Results window 


FM_GETSELCOUNT 


Parameters 


~ Return Value 


See Also 


A File Manager extension sends a FM_GETSELCOUNT message to retrieve a 
count of the selected files in the directory or the veaien Results window, depend- 


Ing on which is the active window. 


wParam 
Not used. 


lParam 
Not used. 


The return value is the number of selected files. 


FM_GETFILESEL, FM_GETFILESELLEN, FM_GETSELCOUN TLFEN 


FM_ GETSELCOUNTLFN 


Parameters 


A File Manager extension sends an FM _GETSELCOUNTLEN message to re- _ 
trieve the number of selected files in the directory or the Search Results window, 


‘depending on which is the active window. The count includes files that have elong 
_ filenames. 


wParam — 
Not used. 


[Param — 
Not used. 


538 FM_REFRESH_WINDOWS 


Return Value 


Comments 


See Also 


The return value is the number of selected files. 


Only extensions that support long filenames (for example, network-aware exten- 
sions) should use this message. 


FM_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNT 


FM_REFRESH_WINDOWS 


Parameters 


Return Value 


Comments 


See Also 


A File Manager extension sends an FM_REFRESH_WINDOWS message to 
cause File Manager to repaint either its active window or all of its windows. 


wParam 
Specifies whether File Manager repaints its active window or all of its win- 
dows. If this parameter is nonzero, File Manager repaints all of its windows. If 
this parameter is zero, File Manager repaints only its active window. _ 


lParam 
Not used. 


This message does not return a meaningful value. 


File system changes caused by an extension are automatically detected by File 
Manager. An extension should use this message only in situations where drive con- 
nections are made or canceled. | 


FMExtensionProc 


FM_ RELOAD _ EXTENSIONS 


A File Manager extension (or another application) sends a an 
FM_RELOAD_EXTENSIONS message to cause File Manager to reload 
all extension dynamic-link libraries (DLLs) listed in the [AddOns] section 
of the WINFILE.INI file. 


Parameters 


Return Value 


Comments 


See Also 


-FM_RELOAD_EXTENSIONS 539 


wParam 
~ Not used. 


lParam 
Not used. 


This message does not return a meaningful value. 


Other applications can use the PostMessage function to send this message to File 
Manager. To obtain the appropriate File Manager window handle, an application 
can specify WFS_Frame as the /pszClassName parameter in a call to the Find- 
Window function. 


Find Window, FMExtensionProc, PostMessage 


Control Panel Messages 


Chapter S | 
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CPL_DBLCLK 043 


Control Panel communicates with a Control Panel dynamic-link library (DLL) 
through messages it sends to the CPlApplet entry-point function. A message con- 
sists of three parts: a message number and two 32-bit parameters. Message num- 
bers are identified by predefined message names. The two 32-bit parameters 
contain message-dependent values. 


This chapter contains an alphabetic list of all messages that can be received by the 
CPIApplet entry-point function. To use these messages, you must include the 


~CPL.H header file. 


cPL_ DBLCLK “ 


Parameters 


Return Value 


Comments 


See Also 


The CPL... DBLCLK. message is sent to a Control Panel dynamic- link library 
(DLL) when the user double-clicks the icon of an application supported by the 
DLL. 


lParam! | 
Specifies the application number. This number must be in the range zero 
through one less than the value returned in response to the CPL_GETCOUNT 
message (CPL_GETCOUNT - 1). 


lParam2 
Specifies the value loaded into the IData memiber for the application. 


The Control Panel DLL returns zero if it processes this message sian 


In response to this message, a Control Panel DLL should display the dialog box 
for the application. 


: CPL_GETCOUNT 


544 CPL_EXIT 


CPL_ EXIT 


Parameters 


Return Value 


Comments 


[ 3.1 | 


The CPL_EXIT message is sent once to a Control Panel dynamic-link library 
(DLL) before Control Panel calls the FreeLibrary function to free the DLL. 


lParam] 
_ Not used. 


lParam2 
Not used. 


The Control Panel DLL returns zero if it processes this message successfully. 


In response to this message, a Control Panel DLL should free any memory that it 
has allocated and perform global-level cleanup. 


cPL_ GETCOUNT sat aa] 


Parameters 


Return Value 
Comments — 


See Also 


The CPL_GETCOUNT message retrieves the number of applications a Control 
Panel sa link library (DLL) services. 


( 


lParam! 
Not used. 


lParam2 
_ Not used. 


The Control Panel DLL returns the number of applications it services. 


- ‘This message is sent immediately after the CPL_INIT message. 


CPL_INIT 


CPL_INIT 
Parameters 


Return Value 


Comments 


CPL_INQUIRE 


~ Parameters 


 CPLLINIT) =—s 4545 


[ 3.1 | 


The CPL_INIT message prompts a Control Panel dynamic-link library (DLL) to 
perform global initialization, especially memory allocation. | 


lParam! 
Not used. 


lParam2 
Not used. 


The Control Panel DLL returns nonzero if initialization is successful. Otherwise, it 
returns zero. If the DLL returns zero, Control Panel calls the Reser func- 
tion and ends communication with the DLL. 


Because this is the only way a Control Panel DLL can signal an error condition, 
the DLL should allocate memory in response to this message. 


This message is sent immediately after the DLL is loaded. 


The CPL_INQUIRE message is sent to a Control Panel dynamic-link library 
(DLL) to request information about an application that the DLL supports. 


This message is provided for backward compatibility with the Microsoft Windows 
operating system, version 3.1. An application should use the CPL ir aes | 
message instead of the CPL_INQUIRE message. | 


l[Paraml | 
_ Specifies the application number. This number must be i in the t range zero 
through one less than the value returned in response to the CPL_ GETCOUNT 
message (CPL_GETCOUNT - 1). 


546 CPL_INIT 


lParam2 | 
Specifies a far pointer to a CPLINFO structure. The DLL should fill this struc- 
ture with resource identifiers for the icon, short name, description, and any user- 
defined value associated with the application. The CPLINFO structure has the 
following form: 


#Hinclude <cp1.h> 


typedef struct tagCPLINFO { /* cpli */ 
int idicon; 
int idName; 


int idInfo; 
LONG 1Data; 
} CPLINFO; 
Return Value The Control Panel DLL returns zero if it processes this message successfully. 
Comments | This message is sent once for each application serviced by the DLL. It is sent im- 


mediately after the CPL_GETCOUNT message. A DLL can perform application- 
level initialization when it receives this message. Memory should be allocated in 
response to the CPL_INIT message. 


See Also CPL_GETCOUNT, CPL_INIT, CPL_NEWINQUIRE 


CPL_NEWINQUIRE 


The CPL_NEWINQUIRE message is sent to a Control Panel dynamic-link library 
(DLL) to request information about an application that the DLL supports. 


Parameters [Param | 
Specifies the application number. This number must be in the range zero 
through one less than the value returned in response to the CPL_GETCOUNT 
message (CPL_ GETCOUNTE- I). 


[Param2 
Specifies a far pointer to a NEWCPLINFO structure. The DLL should fill this 
structure with information about the application. The NEWCPLINFO struc- 
ture has the following form: 


Return Value 


Comments 


See Also 


CPL_INIT 947 


#Hinclude <cpl.h> 


typedef struct tagNEWCPLINFO { /* ncpli */ 
DWORD dwSize; 
DWORD dwFlags; 
DWORD dwHelpContext; 
LONG 1Data; 
HICON  hlIcon; 
char szName[32]; 
char szInfo[l64]; 
char Sears ee 
} NEWCPLINFO; 


The Control Panel DLL returns zero if it processes this message successfully. 
This message is sent once for each application serviced by the DLL. It is sent im- 
mediately after the CPL_GETCOUNT message. A DLL can use the switch block 
for this message to do application-level initialization when it receives this mes- 


sage. Memory should be allocated in response to the CPL_INIT message. — 


CPL_GETCOUNT, CPL_INIT, CPL_INQUIRE 


CPL_SELECT 


Parameters 


Return Value 


The CPL_SELECT message is sent to a Control Panel dynamic-link library (DLL) 
when the user selects the icon of an application supported by the DLL from 
Control Panel. 


[Param 
Specifies the seOHCHIO number. 
lParam2 


Specifies the application-defined value loaded in the IData member for the ap- 
plication. ghee 


The Control Panel DLL returns zero if it processes this message successfully. 


048 CPL_INIT 


CPL_STOP 


The CPL_STOP message is sent once for each application when Control Panel 
ends. 


Parameters IParam1 | 
Specifies the application number. This number must be in the range zero 
through one less than the value returned in response to the CPL_GETCOUNT 
message (CPL_GETCOUNT - 1). 


lParam2 ; : 
Specifies the application-defined value loaded in the IData member for the ap- 
plication. | 
Return Value _ The Control Panel DLL returns zero if it processes this message successfully. 
Comments In response to this message, a Control Panel DLL should perform application- 


specific cleanup. 


See Also CPL_GETCOUNT | 


WM_CPL_LAUNCH 


An application sends the WM_CPL_LAUNCH message to Control Panel to re- 
quest that a Control Panel application be started. 


Parameters wParam 


Specifies the handle of the window sending the message. The 
WM_CPL_LAUNCHED message is sent to this window. | 


[Param | | 
Specifies a far pointer to a string containing the name of the application to open. 


Return Value §—* The return value is nonzero if the application was launched. Otherwise, it is zero. 


Comments The string referenced by the /Param parameter must be contained in a global 
memory object allocated with the GMEM_NOT_BANKED flag. 


See Also WM_CPL_LAUNCHED 


CPL_INIT 949 


WM_CPL_LAUNCHED 


Parameters 


Return Value. 


See Also 


The WM_CPL_LAUNCHED message is sent when a Control Panel 
application, started by the WM_CPL_LAUNCH message, has ended. 

The WM_CPL_LAUNCHED message is sent to the window identified by _ 
the wParam parameter of the WM_CPL_LAUNCH mesetee that started the 
application. 


| ee 


Specifies whether the application was started. If the application was started this 
parameter is nonzero. Otherwise, it is zero. | 


lParam 
Not used. 


The value returned by the application is ignored for this message. 


WM_CPL_LAUNCH 


i 


Common Dialog Box Messages 
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COLOROKSTRING 553 


A common dialog box sends a message to notify applications that the user has 
made or changed a selection in the dialog box. Applications can use these mes- 
sages to carry out custom actions, such as pelecane certain user selections or set- 
ting custom colors. | 


Before an application can use a common sidloe box message, it must register that 
message by using the RegisterWindowMessage function and the message con- 
stants given in this chapter and defined in the COMMDLG.H header file. 


This chapter describes the common dialog box messages. The messages appear in 
alphabetic order. 


COLOROKSTRING = [aa] 


Parameters 


Return Value 


Comments 


See Also 


The COLOROKSTRING message is sent by the Color dialog box to the appli- 
cation’s hook function immediately before the dialog box is closed. This message 
allows more control over custom colors by giving the application the opportunity 


__ to leave the Color dialog box open when the user presses the OK button. 


wParam 
Not used. 
lParam 


Points to a CHOOSECOLOR structure that specifies t the currently selected | 
color. 


If the application returns a nonzero value when it processes this message, the _ 
dialog box is not dismissed. 


To use this message, the application must create anew message identifier by call- — 
ing the RegisterWindowMessage function and passing the COLOROKSTRING 
constant as the single parameter. 


Register WindowMessage 


554 FILEOKSTRING 


- FILEOKSTRING =. ee rs 


The FILEOKSTRING message is sent by the Open dialog box or Save As dialog 
box to the application’s hook function when the user has selected a filename and 
chosen the OK button. The message lets the application accept or reject the user- 
selected filename. 


Parameters wParam 
? Not used. 


lParam 
Points to an OPENFILENAME structure containing information about the 
user’s selection. (This information includes the filename for the selection.) 


Return Value The hook function should return 1 if it rejects the user-selected filename. In this 
case, the dialog box remains open and the user must select another filename. The 
hook function should return 0 if it accepts the user-selected filename or does not 
process the message. 


Comments To use this message, the application must create a message identifier by using the 
- RegisterWindowMessage function and passing the FILEOKSTRING constant as 
the function’s single parameter. 


See Also - RegisterWindowMessage 


FINDMSGSTRING oa 


The FINDMSGSTRING message is sent to the application by the Find dialog box 
or Replace dialog box whenever the user has typed selections and chosen the OK 
button. This message contains data specified by the user in the dialog box controls, 
such as the direction in which the application should search for a string, whether 
the application should match the case of the specified string, or whether the appli- 

_ cation should match the string as an entire word. | 


Parameters wParam 
Not used. 
lParam 


Points to a FINDREPLACE structure containing information about the user’s 
selections. 


Return Value 


Comments 


See Also 


HELPMSGSTRING 555 


The application should return zero. 

To use the FFNDMSGSTRING message, the application must create a 
message identifier by using the RegisterWindowMessage and passing the 
FINDMSGSTRING constant as the function’s only parameter. 


RegisterWindowMessage 


HELPMSGSTRING cries 


Parameters 


Return Value 


Comments 


See Also 


The HELPMSGSTRING message is sent by a common dialog box to its owner’s 
window procedure whenever the user chooses the Help button. This message lets 
an application provide custom Help for the common dialog boxes. 


wParam 
- Not used. 


[Param 


Points to the structure that describes the common dialo 8 box. 


- The ‘plication returns zero. 


To use the HELPMSGSTRING message, the application must create a message 


identifier by using the Register WindowMessage function and passing the 
HELPMSGSTRING constant as the function’s single parameter. 


In addition to creating a new ‘message identifier, the application must set the 
hwndOwner member in the appropriate data structure for the common dialog 
box. This member must contain the handle of the window to receive the 


-HELPMSGSTRING message. 


The application can also process the request for Help in a hook function. The hook 
function would identify this request by checking whether the wParam parameter 
of the WM _ COMMAND message was equal to psh 15. 


Register WindowMessage 


096 LBSELCHSTRING 


LBSELCHSTRING [3.1 | 


The LBSELCHSTRING message is sent to an application’s hook function by the 
Open or Save As‘dialog box whenever the user makes or changes a selection in the 
File Name list box. This message lets an application identify a new selection and 
carry out any application-specific actions, such as updating a custom control in the 
dialog box. 


Parameters wParam | 
Identifies the list box in which the selection occurred. 


[Param 
_ Identifies the list box item and type of selection. The low-order word of the 
lParam parameter identifies the list box item. The high-order word of the 
lParam parameter is one of the following values: 


Value Meaning 


CD_LBSELCHANGE _ Specifies that the item identified by the low-order word 
of [Param was the item in a single-selection list box. 


CD_LBSELSUB Specifies that the item identified by the low-order word 
of /Param is no longer selected in a multiple-selection 
| list box. — 
CD_LBSELADD Specifies that the item identified by the low-order word 
_ _ of [Param was selected from a multiple-selection list 
box. | 
CD_LBSELNOITEMS Specifies that no items exist in a multiple-selection list 
box. © | 
Return Value The application returns zero. 
Comments To use the LBSELCHSTRING message, the application must create a message 


identifier by using the RegisterWindowMessage function and passing the 
LBSELCHSTRING constant as the function’s single parameter. 


See Also -RegisterWindowMessage 


SHAREVISTRING Jo/ 


SETRGBSTRING = eens 


The SETRGBSTRING message is sent by an application’s hook function to a 
Color dialog box to set a custom color. 


Parameters wParam 
| Not used. 


lParam 
Specifies the color to set. This parameter must be a red, green, blue (RGB) 
value. 


Return Value This message has no return value. 


Comments To use the SETRGBSTRING message, the application must create a message 
identifier by using the RegisterWindowMessage function and passing the 
~SETRGBSTRING constant as the function’s single parameter. 


See Also Register WindowMessage 


SHAREVISTRING a ae oie 


The SHAREVISTRING message is sent to the application’s hook function by the 
Open or Save As dialog box if a sharing violation occurs when the dialog box tries 
to open a file on the network. | 


Parameters wParam 
Not used. 


[Param 
Points to a string identifying the path and Alewimne that caused the sharing viola- 
tion. This string is the szPathName member of the OFSTRUCT structure that | 
is pointed to by the oe parameter of the OpenFile function. 


Return Value The return value is described in the following Comments section. 
Comments To use the SHAREVISTRING message, the application must create a message 


identifier by using the Register WindowMessage function and passing the 
SHAREVISTRING constant as the function’s single parameter. 


508 SHAREVISTRING 


This message is sent by the OpenFile function. The message is not sent 
when the OFN_SHAREAWARE flag is set in the me member of the 
OPENFILENAME structure. 


When the hook function receives SHAREVISTRING, it should 
return OFN_SHAREWARN, OFN_SHARENOWARN, or 
OFN_SHAREFALLTHROUGH. For more information about these 
flags, see the description of the OPENFILENAME structure in 
Chapter 3, “Structures.” 


See Also _ OpenFile, Register WindowMessage 
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DRV_CLOSE 961 


Installable driver messages notify installable drivers of specific events, such as 
loading or unloading the driver, or direct the driver to carry out some action, such 
as displaying a configuration dialog box. The Microsoft Windows operating sys- 
tem, version 3.1, sends installable driver messages to the DriverProc function of 
an installable driver whenever an application calls functions, such as OpenDriver, 
SendDriverMessage, and CloseDriver. 


This chapter lists the installable driver messages in alphabetic order. 


DRV_CLOSE _ ar] 


The DRV_CLOSE message is the first message sent by Windows to an installable 
driver after an application calls the CloseDriver function. 


Parameters dwDriverldentifier 
Specifies the unique 32-bit identifier returned by the OpenDriver function. 


hDriver 
Identifies the instance of the installable driver that should be closed. 


lParam! 
Specifies driver-specific data. 


[Param2 — | 
Specifies driver-specific data. 


Return Value _ An installable driver returns nonzero if its DriverProc function successfully 
closes the driver. Otherwise, it returns zero. 


Comments The /ParamI1 and |Param2 parameters specify the same values as the iParaml and 
/[Param2 parameters for the CloseDriver function. 


Each time a driver processes this message, it must decrement a private use-count 
variable. When the value of this variable is zero, Windows closes the driver. 


See Also DRV_OPEN 


962 DRV_CONFIGURE 


DRV_CONFIGURE he . 


The DRV_CONFIGURE message is sent to inform an installable driver that it 
should display its private configuration dialog box. 


Parameters dwDriverldentifier 
Specifies a unique 32-bit value that identifies the installable driver. 


hDriver 
Identifies an instance of the installable driver. 


lParam! 
Specifies the handle of the parent window for the configuration dialog box. 
This handle is in the parameter’s low-order word. 


[Param2 | 
Points to an optional DRVCONFIGINFO structure. An installable driver 
should verify that this pointer is valid before using it. 


This structure has the following form: 


typedef struct tagDRVCONFIGINFO { 
DWORD dwDCISize;_ 
LPCSTR IpszDCISectionName; 
LPCSTR IpszDCIAliasName; 

} DRVCONFIGINFO; 


Return Value An installable driver returns nonzero if it processes this message. Otherwise, it re- 
turns zero. | 
Comments An installable driver that supports the DRV_CONFIGURE message must 


provide its own dialog box template and dialog box procedure. It must also 
record the user’s configuration requests in an appropriate file. (This may be the 
_ SYSTEM.INI file or some other file used by the driver for this purpose.) 


See Also DRV_QUERYCONFIGURE 


DRV_ ENABLE 963 


DRV_DISABLE 3=—s_—i‘wte on 


Parameters 


‘Return Value 


See Also 


The DRV_DISABLE message is the second message sent by Windows to an in- 
stallable driver after an application calls the CloseDriver function. 


dwDriverldentifier 
Not used. 


hDriver 
Identifies an instance of the installable driver. 


| lParaml 


Not used. 


lParam2 
Not used. 


An installable driver returns zero if it processes this message. 


DRV_CLOSE 


DRV_ENABLE Ee a 


Parameters 


The DRV_ENABLE message is sent to an installable driver when it is loaded or 
reloaded or whenever Windows is reinstalled after switching to an MS-DOS appli- 
cation. | | | 


dwDriverldentifier 
Not used. 
hDriver 
Identifies an instance of the installable driver. 


lParaml 
Not used. 


lParam2 
Not used. 


964 DRV_EXITAPPLICATION 


Return Value » An installable driver returns zero if it processes this message. 


Comments When the DriverProc function receives this message, it should initialize all of the 
driver-specific structures with default values. 


See Also DRV_OPEN 


DRV_EXITAPPLICATION oa 


The DRV_EXITAPPLICATION message is sent to all installable drivers when an 


application exits. 
Parameters dwDriverldentifier | 

Specifies a unique 32-bit value that identifies the installable driver. 

lParam! : 
Specifies the type of application exit. This parameter can be one of the follow- 
ing values: | 
Value Meaning 
DRVEA_NORMALEXIT Set if the application terminated normally. 


-DRVEA_ABNORMALEXIT _ Set if the application terminated abnormally 
(because of an application or system error). 


- [Param2 
Not used. 


Return Value The value returned by the application is ignored for this message. 


See Also DRV_EXITSESSION 


DRV_FREE 565 


DRV_EXITSESSION 7 


Parameters 


Return Value 
~ Comments — 


See Also | 


DRV_FREE 


Parameters 


Return Value 


Comments 


The DRV_EXITSESSION message is sent to all installable drivers when Win- 
dows prepares to exit. 


dwDriverldentifier 
Specifies a unique 32-bit value that identifies the installable driver. 


1Param1 
Reserved. 


lParam2 
Reserved. 
The value returned by the application is ignored for this message. 


The user interface and all other drivers are still enabled when this message is sent. 


DRV_EXITAPPLICATION 


[ 3.1 | 


The DRV_FREE message is the third message sent by Windows to an installable 
driver after an application calls the CloseDriver function. 


dwDriverldentifier 
Not used. 


hDriver 
Identifies an instance of the installable driver. 


[Param 
Not used. 


[Param2 
Not used. 


An installable driver returns zero if it processes this message. 


_ When an installable driver’s DriverProc function receives this message, it should 


free the memory that was allocated for all driver-specific structures. 


— 966 DRV_INSTALL 


DRV_INSTALL mo, ra] 


The DRV_INSTALL message is sent to an pistalane driver during the driver in- 
itialization process. 


_ Parameters dwDriverldentifier 
Specifies a unique 32-bit value that identifies the installable driver. 


hDriver 
Identifies an instance of the installable driver. 


lParam! 
Not used. 


l[Param2 
- Points to an optional DRVCONFIGINFO structure. An installable driver — 
should verify that this pointer is valid before using it. 


This structure has the following form: 


typedef struct tagDRVCONFIGINFO { 
DWORD dwDCISize; 
LPCSTR IpszDCISectionName; 
LPCSTR IpszDCIAliasName; 

} DRVCONFIGINFO; | 


Return Value An installable driver returns nonzero if it processes this message. Otherwise, it re- 
| turns zero. 
Comments When the driver receives this message, it creates an entry for the driver in the 


SYSTEM.INI file and performs other necessary configuration operations. 


DRV_LOAD eS aa] 


The DRV_LOAD message is sent to an installable driver to notify the driver that it 
has been loaded. 


Parameters = dwDriverldentifier 
Not used. 


hDriver 
Identifies an instance of the installable driver. © 


Return Value 


DRV_OPEN 567 


lParam! 
Not used. 


lParam2 | 
Not used. 


An installable driver returns nonzero if its DriverProc function successfully loads 


the driver. Otherwise, it returns zero. : 


DRV_ OPEN. 


Parameters 


Return Value 
Comments 


| See Also 


The DRV_OPEN message is sent to an installable driver each time it is opened. | 


dwDriverldentifier 
Specifies a unique 32-bit value that identifies the installable driver. 


hDriver 
Identifies an instance of the installable driver. 


[Paraml 
Points to a null-terminated string containing any ASCII characters that followed 
the driver name in the SYSTEM.INI file. , 


[Param2 
Contains the data specified by the lParam ren the third argument in the 
OpenDriver function. 


An installable driver returns nonzero if it processes this message. Otherwise, it re- 
turns zero. | 


If no characters follow the driver name in SYSTEM. INI, the /Param1 parameter 1S 
a NULL pointer. 


DRV_CLOSE 


968 DRV_POWER 


DRV_POWER — . [3.1 | 


The DRV_POWER message is sent to an installable driver each time the power 
supply to the associated device is about to be turned on or off. 


Parameters | dwDriverldentifie ier 
| Specifies a unique 32-bit value that identifies the installable driver. 


hDriver 
Identifies an instance of the installable driver. 


lParaml 
Not used. 


lParam2 
Not used. 


Return Value An installable driver returns nonzero if it processes this message. Otherwise, it re- 
turns zero. 


DRV_QUERYCONFIGURE 4 a 


The DRV_QUERYCONFIGURE message is sent to an installable driver to deter- 
mine whether it can be configured by the user. 


- Parameters dwDriverldentifier | 
Specifies a unique 32-bit value that identifies the installable driver. 


hDriver 
Identifies an instance of the installable driver. 


lParam! 
Not used. 


lParam2 
Not used. 


Return Value An installable driver returns nonzero if it supports custom configuration and is 
capable of displaying a configuration dialog box. Otherwise, it returns zero. 


See Also DRV_CONFIGURE 


DRV_USER 969 


DRV_REMOVE [84] 


The DRV_REMOVE message is sent by an application to an installable driver to 
notify the driver that it is about to be removed from the system. 


Parameters dwDriverldentifier 
Specifies a unique 32-bit value that identifies the installable driver. 


lParam. 
Not used. 


lParam2 
Not used. 


Return Value An installable driver returns nonzero if it processes this message. Otherwise, it re- 
turns zero. 


Comments When an installable driver receives this message, it should remove necessary en- 
: tries from the SYSTEM_INI file. 


~DRV_USER ; (8A 


The DRV_USER message is a user-defined or driver-dependent message. 


Parameters dwDriverldentifier : 
This parameter is not predefined: the value is driver dependent. 


hDriver 
This parameter is not predefined; the value is driver dependent. 


lParam! 
This parameter is not predefined; the value is driver dependent. 


[Param2 
This pores is not predefined; the value is driver dependent. 


Return Value = ~The return value is driver dependent. 
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This appendix lists and describes the binary and ternary raster operations used 
by graphics device interface (GDI). A binary raster operation involves two oper- 
ands: a pen and a destination bitmap. A ternary raster operation involves three 
operands: a source bitmap, a brush, and a destination maunap Both binary and 
ternary raster operations use Boolean operators. 


A.1 Binary Raster Operations 


This section lists the binary raster-operation codes used by the GetROP2 and 
SetROP2 functions. Raster-operation codes define how GDI combines the bits 
from the selected pen with the bits in the destination bitmap. | 


Each raster-operation code represents a Boolean operation in which the values of 
the pixels in the selected pen and the destination bitmap are combined. Following - 
are the two operands used in these operations: 


Operand Meaning 
P : Selected pen 
D Destination bitmap 


The Boolean operators used in these operations follow: 


Operator §=§ Meaning 
8 Bitwise AND 
n Bitwise NOT (inverse) 
re) Bitwise OR 
X Bitwise exclusive OR (XOR) 


All Boolean operations are presented in reverse Polish notation. For example, the 
following operation replaces the values of the pixels in the destination bitmap with 
a combination of the pixel values of the pen and the selected brush: 


DPo 
Each raster-operation code is a 32-bit integer whose high-order word is a Boolean 


operation index and whose low-order word is the operation code. The 16-bit opera- 
tion index is a zero-extended 8-bit value that represents all possible outcomes 
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resulting from the Boolean operation on two parameters (in this case, the pen and 
destination values). For example, the operation indexes for the DPo and DPan 
Operations are shown in the following list: 


P D DPo DPan 
1 


— ee C © 
—_ C&O —= © 
—_- -_ pS CD) 


1 
1 
0 


The following list outlines the drawing modes and the Boolean operations that 


they represent: 

Raster operation Boolean operation 
R2_BLACK 0 

R2_COPYPEN P 
R2_MASKNOTPEN DPna 
R2_MASKPEN DPa 


R2_MASKPENNOT PDna 
R2_MERGENOTPEN DPno 


R2_ MERGEPEN DPo 
R2_MERGEPENNOT _ PDno 
R2_NOP D 
R2_ NOT Dn 
R2_NOTCOPYPEN Pn 


R2_NOTMASKPEN DPan 
R2_NOTMERGEPEN DPon 


R2_NOTXORPEN DPxn 
R2_WHITE 1 
R2 XORPEN DPx 


For a monochrome device, GDI maps the value zero to black and the value 1 to. 
white. If an application attempts to draw with a black pen on a white destination 
by using the available binary raster operations, the following results occur: 


Raster operation Result 
R2_BLACK Visible black line 
R2_COPYPEN Visible black line 
R2 MASKNOTPEN | No visible line 
R2 MASKPEN Visible black line 


R2_MASKPENNOT _ Visible black line 


Raster operation 


R2_MERGENOTPEN 
R2_MERGEPEN 
R2_MERGEPENNOT 
R2_NOP 

R2_NOT 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 
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Result 


No visible line 


Visible black line 


Visible black line 
No visible line 
Visible black line 
No visible line 
No visible line 
Visible black line 
Visible black line 
No visible line 
No visible line 


9/9 


For a color device, GDI uses RGB values to represent the colors of the pen and the 
destination. An RGB color value is a long integer that contains a red, a green, and 
a blue color field, each specifying the intensity of the given color. Intensities range 
from 0 through 255. The values are packed in the three low-order bytes of the long 
integer. The color of a pen is always a solid color, but the color of the destination 


may be a mixture of any two or three colors. If an application attempts to draw 


with a white pen on a blue destination by using the available binary raster opera- 
tions, the following results occur: 


Raster operation 


R2_BLACK 
R2_COPYPEN 
R2_MASKNOTPEN 
R2_MASKPEN 
R2_MASKPENNOT 


~R2_MERGENOTPEN 


R2_MERGEPEN 
R2_MERGEPENNOT 
R2_NOP 

R2_ NOT 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 


Result 


i Visible black line 


Visible white line 
Visible black line 
Invisible blue line 
Visible red/green line 
Invisible blue line 
Visible white line 
Visible white line 
Invisible blue line 
Visible red/green line 
Visible black line 
Visible red/green line 
Visible black line 
Invisible blue line 
Visible white line 
Visible red/green line 


9/6 
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A.2 Ternary Raster Operations 


- This section lists the ternary raster-operation codes used by the BitBIt, PatBlt, and 


StretchBlt functions. Ternary raster-operation codes define how GDI combines 
the bits in a source bitmap with the bits in the destination bitmap. 


Each raster-operation code represents a Boolean operation in which the values of | 
the pixels in the source, the selected brush, and the destination are combined. Fol- 
lowing are the three operands used in these operations: 


Operand Meaning 


D Destination bitmap 
P Selected brush (also called pattern) 
S Source bitmap 


Boolean operators used in these operations follow: 


Operator Meaning 

a Bitwise AND 

n Bitwise NOT (inverse) 

O Bitwise OR — 

x Bitwise exclusive OR (XOR) 


All Boolean operations are presented in reverse Polish notation. For example, the 
following operation replaces the values of the pixels in the destination bitmap with 
a combination of the pixel values of the source and brush: 


PSo 
The following operation combines the values of the pixels in the source and brush 
with the pixel values of the destination bitmap (there are alternative spellings of 


the same function, so although a particular spelling may not be in the list, an 
eam arc form would be): 


DPSoo 
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Each raster-operation code is a 32-bit integer whose high-order word is a Boolean 
operation index and whose low-order word is the operation code. The 16-bit opera- 
tion index is a zero-extended, 8-bit value that represents the result of the Boolean 
operation on predefined brush, source, and destination values. For example, the. 
operation indexes for the PSo and DPSoo operations are shown in the following 
list: 


S D PSo DPSoo 
0 0 0 0 0 
0 0 1 0 l 
0 ] 0 1 1 
0 1 1 1 1 
1 0 0 1 1 
1 0) 1 1 1 
1 1 0 1 1 
1 1 1 1 1 | 
Operation index: OOFCh OOFEh 


In this case, PSo has the operation index OOFC (read from the bottom up); DPSoo 
_has the operation index OOFE. These values define the location of the correspond- 
ing raster-operation codes, as shown in Table A.1, “Raster-Operation Codes.” The 
PSo operation is in line 252 (OOFCh) of the table; DPSoo is in line 254 (OOFEh). 


The most commonly used raster operations have been given special names in the 
Windows include file, WINDOWS.H. You should use these names whenever 
possible in your applications. 


When the source and destination bitmaps are monochrome, a bit value of zero 
represents a black pixel and a bit value of 1 represents a white pixel. When the 
source and the destination bitmaps are color, those colors are represented with 
RGB values. For more information about RGB values, see the RGB structure in 
Chapter 3, “Structures.” 
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Table A.1 Raster-Operation Codes 


Boolean function 
(hexadecimal) | 


00 


01 
02 
03 
04 
05 
06 
07 
08 
09 
OA 
OB 
OC 
OD 
OE 
OF 
10 
11 
12 
13 
14 
15 
16 — 


“17 


18 
19 

1A 
1B 
IC 


1D 


1E 
1F 
20 


21 


22 
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_ Raster operation 


(hexadecimal) 


00000042 
00010289 
00020C89 
000300AA 
00040C88 


~ 000500A9 


00060865 
000702C5 
OO080F08 
00090245 
000A0329 
0O0OBOB2A 
000C0324 
000D0B25 
OOOEO8A5 
OOOF0001 
00100C85 
001100A6 
00120868 


~ 001302C8 


00140869 
001502C9 
00165CCA 
00171D54 
00180D59 
00191CC8 
001A06C5 
001B0768 
001CO06CA 
001D0766 


— OO1EOIAS 


001F0385 
00200F09 
00210248 
00220326 


Boolean function 
in reverse Polish 
0 

DPSoon 

DPSona 

PSon 

SDPona 


~ DPon 


PDSxnon 
PDSaon 
SDPnaa 
PDSxon 
DPna 
PSDnaon 
SPna 
PDSnaon 
PDSonon 
Po 
PDSona 
DSon 
SDPxnon 
SDPaon 
DPSxnon 
DPSaon 
PSDPSanaxx 
SSPxDSxaxn 
SPxPDxa 
SDPSanaxn 
PDSPaox 
SDPSxaxn 
PSDPaox 
DSPDxaxn 


_ PDSox 


PDSoan 


DPSnaa 
~ SDPxon 


DSna 


Common name 


BLACKNESS 


NOTSRCERASE 
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Table A.1 Raster-Operation Codes (continued) 


Boolean function 
(hexadecimal) 
23 
24 
25 
26 
27 
28 
29 | 
2A 
2B 
2C 
2D 
2E 
2F 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
3A 
3B 
3C 
3D 
3E 
3F 


Raster operation 
(hexadecimal) 


00230B24 
00240D55 


~ 00251CC5 


002606C8 
00271868 
00280369 © 
002916CA 
002A0CC9 | 
002B1D58 
002C0784 
002D060A 
002E064A 
002FOE2A 
0030032A 
00310B28 
00320688 
00330008 
003406C4 
00351864 
003601A8 
00370388 
0038078A 
00390604 
003A0644 
003B0E24 
003C004A 
003D18A4 
003E1B24 
003FOOEA 
00400F0A 
00410249 
00420D5D 
00431CC4 
00440328 
00450B29 


Boolean function 
in reverse Polish 
SPDnaon 
SPxDSxa 
PDSPanaxn 
SDPSaox 
SDPSxnox 
DPSxa 
PSDPSaoxxn 
DPSana 
SSPxPDxaxn 
SPDSoax 
PSDnox 
PSDPxox 
PSDnoan 
PSna 
SDPnaon_ 
SDPSoox 

Sn 

SPDSaox 
SPDSxnox _ 
SDPox _ 
SDPoan _ 
PSDPoax © 
SPDnox 
SPDSxox 
SPDnoan 
PSx 
SPDSonox 
SPDSnaox 
PSan 
PSDnaa 
DPSxon 
SDxPDxa 
SPDSanaxn 
SDna 
DPSnaon 


Common name 


NOTSRCCOPY 


~ SRCERASE 
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Table A.1 Raster-Operation Codes (continued) . 


Boolean function 
(hexadecimal) 
46 
47 

48 

49 

4A 

4B 

4C 

4D 

4E 

4F 

50 

51 

52 

53 

54 

55 

56 

57. 

58 


59 


5A 
5B 
SC 
5D 
SE 
SF 
60 
61 
62 
63 
64 
65 
66 
67 
68 


Raster operation 
(hexadecimal) 
004606C6 
0047076A 
00480368 
004916C5 
004A0789 
004B0605 
004COCC8 — 
004D1954 
004E0645 
004FOE25 
00500325 
00510B26 
005206C9 
00530764 
005408A9 
00550009 
005601A9° 
00570389 
00580785 
00590609 
005A0049 
005B18A9 
005C0649 
0O0SDOE29 
005E1B29 
OOSFOOE9 
00600365 
006116C6 
00620786 
00630608 
00640788 
00650606 
00660046 
006718A8 
006858A6 


Boolean function 


in reverse Polish 


DSPDaox 
PSDPxaxn 
SDPxa 
PDSPDaoxxn 
DPSDoax 
PDSnox 
SDPana 
SSPxDSxoxn 
PDSPxox 
PDSnoan 
PDna 
DSPnaon 
DPSDaox 
SPDSxaxn 
DPSonon 

Dn 

DPSox 
DPSoan 
PDSPoax 
DPSnox 

DPx 
DPSDonox 
DPSDxox 
DPSnoan 
DPSDnaox 
DPan 

PDSxa 
DSPDSaoxxn 
DSPDoax 
SDPnox 
SDPSoax 
DSPnox 

DSx 
SDPSonox 
DSPDSonoxxn 


Common name 


DSTINVERT 
PATINVERT 


— 


~ SRCINVERT 
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Table A.1 Raster-Operation Codes | (continued) 


Boolean function 
(hexadecimal) 
69 
6A 
6B 
6C 
6D 
6E 
6F 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
TA 
7B 
7C 
7D 
TE 
7F 
80 
$1 
82 
83 
84 
85 
86 
87 
88 
89 
8A 
8B 


Raster operation 
(hexadecimal) 
00690145 
006A01E9 
006B178A 
006C01E8 
006D1785 
006E1E28 
006F0C65 
00700CC5 
00711D5C | 
00720648 
00730E28 
00740646 
00750E26 
00761B28 
007700E6 
007801E5 
00791786 
007A1E29 
007B0C68 
007C1E24 
007D0C69 | 
007E0955 
007F03C9 
008003E9 


~ 00810975 


00820C49 
0083 1E04 
00840C48 
O00851E05 — 
008617A6 
008701C5 
008800C6 


~ 00891B08 


008A0E06 


~ 008B0666 


Boolean function 
in reverse Polish 
PDSxxn 

DPSax 
PSDPSoaxxn 
SDPax | 
PDSPDoaxxn 
SDPSnoax 
PDSxnan 
PDSana 
SSDxPDxaxn 
SDPSxox 
SDPnoan 
DSPDxox 
DSPnoan 
SDPSnaox 


~DSan 
~ PDSax 


DSPDSoaxxn 
DPSDnoax 
SDPxnan 
SPDSnoax 
DPSxnan 
SPxDSxo 
DPSaan 
DPSaa 
SPxDSxon 
DPSxna 
SPDSnoaxn 
SDPxna 
PDSPnoaxn 
DSPDSoaxx 
PDSaxn 
DSa > 
SDPSnaox 
DSPnoa 
DSPDxoxn 


Common name 


SRCAND | 
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Table A.1 Raster-Operation Codes (continued) 


Boolean function 
(hexadecimal) 
8C 
8D 
8E 
8F 
90 
91 
92 
93 
94 
95 
96 
97 
98 
99 
9A 
9B 
9C 
9D 
OE 
OF 
AO 
Al 
A2 
A3_ 
A4 
A5 
A6é 
A7 
A8 
A9 
AA 
AB 
AC 
AD 
AE 


Raster operation 


(hexadecimal) 


008COE08 
008D0668 
008E1D7C 
OO8FOCES 
00900C45 
0091108 
009217A9 
009301C4 
009417AA 
009501C9 
00960169 
0097588A 
00981888 
00990066 
009A0709 
009B07A8 
009C0704 
009D07A6 
009E16E6 
009F0345 
00A000C9 
00A11B05 
00A20E09 
00A30669 
00441885 
00A50065 
00A60706 
00A707A5 
00A803A9 
00A90189 
00AA0029 
OOAB0889 
00AC0744 
OOADO6E9 
OOAEOB06 


Boolean function 


-in reverse Polish 


SDPnoa 
SDPSxoxn 
SSDxPDxax 
PDSanan 
PDSxna 
SDPSnoaxn 
DPSDPoaxx 
SPDaxn 
PSDPSoaxx | 
DPSaxn © 
DPSxx 
PSDPSonoxx 
SDPSonoxn 
DSxn 
DPSnax 


~ SDPSoaxn 


SPDnax 
DSPDoaxn 
DSPDSaoxx 
PDSxan 
DPa 
PDSPnaoxn 
DPSnoa 
DPSDxoxn 
PDSPonoxn 
PDxn 
DSPnax 
PDSPoaxn 
DPSoa 
DPSoxn 

D 

DPSono 
SPDSxax 
DPSDaoxn > 
DSPnao 


Common name 
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Table A.l Raster-Operation Codes (continued) 


Boolean function Raster operation Boolean function Common name 
(hexadecimal) — (hexadecimal) - in reverse Polish 
AF OOAFO229 DPno — 
BO 0OBOOE0S PDSnoa - 
Bl 00B 10665 PDSPxoxn _ 
B2 00B21974 SSPxDSxox _ 
B3 00B30CE8 SDPanan ~ 
B4 00B4070A PSDnax — 
B5 00B507A9 DPSDoaxn — 
B6 00B616E9 DPSDPaoxx - 
B7 00B70348 SDPxan — 
BS 00B8074A PSDPxax . 
B9 O0OB906E6 DSPDaoxn — 
BA OOBAOBO9 DPSnao — 
BB ~00BB0226 DSno MERGEPAINT 
BC OOBC1CE4 SPDSanax _ | 
BD O0OBDOD7D SDxPDxan — 
BE 00BE0269 DPSxo = 
BF OOBFO8C9 DPSano — 7 
CO 0OCOO00CA - PSa 3 MERGECOPY 
Cl 00C11B04 SPDSnaoxn — 
C2 00C21884 SPDSonoxn _ 
C3 00C3006A PSxn — 
C4 00C40E04 SPDnoa — 
C5 —00C50664 SPDSxoxn -- 
C6 00C60708 SDPnax _ 
C7 0O0C707AA PSDPoaxn - 
C8 00C803A8 SDPoa — 
C9 00C90184 SPDoxn — 
CA 00CA0749 DPSDxax | - 
CB O0OCBO6E4 SPDSaoxn — — 
CC 00CC0020 S SRCCOPY 
CD 00CD0888 - SDPono — 
CE ~ QOCEOB08 ~ SDPnao - 
CF ~~ QOCF0224 SPno © — 
DO — QODOOEOA PSDnoa os 
D1 00D1066A -PSDPxoxn = 
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Table A.1 Raster-Operation Codes (continued) 


Boolean function 
(hexadecimal) 
D2 
D3 
D4 
D5 
D6 
D7 
D8 
D9 
DA 
DB 
DC 
DD 
DE 
DF 
EO 
El 
E2 
E3 
E4 
ES 
E6 
E7 
E8 
E9 
EA 
EB 
EC 
ED 
EE 


te oh ws 


FO 
Fl 
F2 
F3 
F4 


Raster operation 
(hexadecimal) 
00D20705 
00D307A4 
00D41D78 
OODSOCE9 
Q0OD616EA 
00D70349 
00D80745 
00D906E8 


- OODAICE9 


OODBOD75 
OODCOB04 
00DD0228 


~ 00DE0268 


OODF08C8 
OOE003A5 
00E10185 
00E20746 
OOE306EA 
00E40748 
OOESO6ES 
00E61CE8 
00E70D79 
00E81D74 


OOE9SCE6 


OOEA02E9 
O0OEB0849 
OOEC02E8 
O0OED0848 
OOEE0086 
OOEFOA08 
0OF00021 
OOF10885 
OOF20B05 
00F3022A 
OOF40B0A — 


Boolean function 


~ in reverse Polish 


PDSnax 
SPDSoaxn 
SSPxPDxax 
DPSanan 
PSDPSaoxx 
DPSxan 
PDSPxax 
SDPSaoxn 
DPSDanax 
SPxDSxan 
SPDnao 
SDno 
SDPxo 
SDPano 
PDSoa 
PDSoxn 
DSPDxax 
PSDPaoxn 
SDPSxax 
PDSPaoxn 
SDPSanax 
SPxPDxan 
SSPxDSxax 
DSPDSanaxxn 
DPSao 
DPSxno 
SDPao 
SDPxno 
DSo 
SDPnoo 

P 

PDSono 
PDSnao 
PSno 


- PSDnao 


Common name 


md 
— 


SRCPAINT 


PATCOPY 
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Table A.1 Raster-Operation Codes (continued) 


Boolean function Raster operation Boolean function Common name 


(hexadecimal) (hexadecimal) in reverse Polish 
F5 OOF50225 PDno _ 
F6 00F60265 PDSxo ~ 
F7 OOF708C5 PDSano — 
F8. OOF802E5 PDSao — 
F9 00F90845 PDSxno — 
FA OOFA0089 DPo — 
FB OOFBOA09 DPSnoo PATPAINT 
FC OOFCOO8A PSo _ 
FD OOFDOA0A PSDnoo — Nites 
FE OOFE02A9 ~ DPSoo — 


FF — OOFFO062 1 WHITENESS 


Virtual-Key Codes 


Numeric Key Codes 


) Appendix B 


AppendixB Virtual-Key Codes $589 


The following table shows the symbolic constant names, hexadecimal values, and 
keyboard equivalents for the virtual-key codes used by the Microsoft Windows 
operating system version 3.1. The codes are listed in numeric order. 


Symbolic constant name. Value (hexadecimal) Mouse or keyboard 
equivalent 
VK_LBUTTON | 01 Left mouse button 
VK_RBUTTON 02. Right mouse button 
VK_CANCEL 03 Used for control-break 
processing 
VK_MBUTTON 04 Middle mouse button 
(three-button mouse) 
~ 05-07 Undefined 
VK_BACK 08 BACKSPACE key 
VK_TAB 09 TAB key 
OA-—OB Undefined | 
VK_CLEAR OC CLEAR key 
-VK_RETURN 0D ENTER key 
= - OE-OF Undefined 
VK_SHIFT 10 _ SHIFT key 
~VK_CONTROL 11 CTRL key 
VK_MENU 12: ALT key 
VK_PAUSE 13 PAUSE key 
VK_CAPITAL 14 CAPS LOCK key | 
— | 15-19 © Reserved for Kanji systems 
— 1A Undefined 
VK_ESCAPE IB _ ESC key 
_ 1C—-1F _ Reserved for Kanji er 
VK_SPACE 20 SPACEBAR 
VK_PRIOR 21 PAGE UP key 
VK_NEXT 22 PAGE DOWN key 
VK_END 23 END key 
VK_HOME 24 HOME key 
VK_LEFT 25 LEFT ARROW key 
VK_UP 26 UP ARROW key 
-VK_RIGHT 27 RIGHT ARROW key 
VK_DOWN > 28 DOWN ARROW key 
VK_SELECT 29 SELECT key 
_ 2A OEM specific 
VK_EXECUTE 2B EXECUTE key 
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Symbolic constant name Value (hexadecimal) Mouse or keyboard 


equivalent 
VK_SNAPSHOT 2C PRINT SCREEN key for 
| Windows 3.0 and later 
VK_INSERT 2D INS key 
VK_DELETE 2E DEL key 
VK_HELP 2F HELP key 
VK_0 30 0 key 
~VK_1 31 1 key 
VK_2 32 | 2 key 
VK_3 33 3 key 
VK_4 34 4 key 
VK_5 35 5 key 
VK_6 36 6 key 
VK_7 37 7 key 
VK_8 38 8 key 
VK_9 39 | 9 key 
— 3A-—40 Undefined 
VK_A 41 A key | 
VK_B 42 B key 
VK_C 43 C key 
VK_D 44 D key 
VK_E 45 E key 
VK_F 46 F key 
VK_G 47 G key 
VK_H 48  Hkey 
VKI "49 I key 
VK_J 4A J key 
~VK_K 4B K key 
VK_L AC | L key 
VK_M 4D M key 
VK_N 4E N key 
VK_O 4F | O key 
VK_P 50 P key 
VK_Q — 51 Q key 
VK R a2 R key 
VK_S 53 = S key 
VK_T 54 T key 


VKU 55 _Ukey 
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Symbolic constant name Value (hexadecimal) Mouse or keyboard 


. | equivalent 

VK_V 56 V key 
VK_W 57 W key 
VK_X | 58 X key 
VK_Y 59 Y key 
VK_Z 5A Z key 
— | 5B-5F Undefined 
VK_NUMPADO 60 Numeric keypad 0 key © 
VK_NUMPAD1 61 Numeric keypad 1 key 
VK_NUMPAD2 62 Numeric keypad 2 key 
VK_NUMPAD3 63 Numeric keypad 3 key 
VK_NUMPAD4 64 Numeric keypad 4 key 
VK_NUMPAD5 65 Numeric keypad 5 key 
VK_NUMPAD6 66 Numeric keypad 6 key 
VK_NUMPAD7 67 Numeric keypad 7 key 
VK_NUMPAD8 68 _ Numeric keypad 8 key 
VK_NUMPAD9 69 | Numeric keypad 9 key 
VK_MULTIPLY 6A Multiply key 
VK_ADD 6B | Add key 
VK_SEPARATOR 6C Separator key 
VK_SUBTRACT 6D : Subtract key 
VK_DECIMAL 6E Decimal key 
VK_DIVIDE 6F Divide key 
VK_F1 70 Fl key 
VK_F2 71 F2 key 
VK_F3 72 F3 key 
VK_F4 73 F4 key 
VK_F5 74 | F5 key 
VK_F6 75 F6 key 
VK_F7 76 F7 key 
VK_F8 — 77 F8 key 

~ VK_F9 78 F9 key 
VK_F10 79 F10 key 
VK_F11 7A Fill key 
VK_F12 ~~ 7B i _ Fl2 key 
VK_F13 7C F13 key 
VK_F14 7D F14 key 


VK_FI15 TE FIS key 
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_. Symbolic constant name 


VK_F16 
VK_F17 
VK_F18 
VK_F19 
VK_F20 
VK_F21 


VK_F22 


VK_F23 
VK_F24 


VK_NUMLOCK 
VK_SCROLL 


Value (hexadecimal) 


Mouse or keyboard 
equivalent 

F16 key 

F17 key» 

F18 key 

F19 key 

F20 key 

F21 key 

F22 key 

F23 key 

F24 key 
Unassigned 
NUM LOCK key 
SCROLL LOCK key 
Unassigned 
OEM specific 
Unassigned 
OEM specific 
Unassigned 
OEM specific 
Unassigned 
OEM specific 
Unassigned 


Character Sets 


‘C.1 ANSI Character Set 


Appendix C 


Sees et cere pace seca ct cincuacsnet eter hace a cceceea ee ieee 596 
Caz - SYMBOL Character DOl weenie Se cctececeut eisai area once eee eas — 597 
C.3. OEM Character Set 


Appendix Character Sets 595 


The Microsoft Windows operating system, version 3.1 supports multiple character 
sets, allowing for customization. Among the character sets that Windows 3.1 pro- 
vides are the Windows, Symbol, and OEM character sets, shown in the following 
sections. | 
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C.1 ANSI Character Set 


ome TN NH BP WO NY KS © 


32 
33 
: 34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 


Indicates that this character is not supported by Windows. 


mwoaeonmwroa mn Fak & G&G ™ 


ay We 


> 
? 


64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 


92 


93 
94 
95 


bo KIN EK EF eCeasunmroeowvwowrz~sar Reese TRO Mm sew lST eA 


96 

97 

98 

99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
7 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 


Pew NE KX FE Cerwrunmt eB TSB SB eB eee Tene aAanera -« 


128 §f 
129 i 
130 ? 


Tr 


31 f 


132 4 


Tr 


133 «++ 


Tr 


134 


Ty 


135. 


Tr 


136 


T 


137 


Tr 


138 


Ty 


139 


Tr 


140 
141 
142 
143 
144 
145 
146 

j47 « 
148» 
149 * 


Tr 


150 — 


Ty 


3151 ome 


T 
15207 
153 TM 
T 

154 

155 


s 
> 
156 Ce 
a 
Hi 


0 


a OR > +++ 


~_ sm meee 


Ty 


Tr 
Tr 


Tr 


157 
158 
Wh59 ¥ 


160 
161 
162 
163 
164 
165 


166 


167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 


Indicates that this character is available only in TrueType fonts. 


oo =-— ££ £ fh <> & 


fs) 


192 


193 


194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 


~ 220 


221 
222 
223 


Sree ao & X SO) oo Se Se ee ee eo oR Oe DD De 


224 
225 
226 
227 
228 


229 


230 
231 
232 
233 
234 
235 
236 
231 
238 
239 
240 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 
252 
253 
254 
255 


@: 2? o) oy Of 32 ck MD oe ey ee DS D> fy OA OR Oe gu da? Ge Gy oe 


So. Gf & + 


=? 


Ves or Ve, &: 


C.2 Symbol Character Set 


oOo OA nN KH A FB WO NY KH CO 


32 
33 
34 
35 
36 
37 
38 
39 
40 
Al 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 


62 
63 


61 


+ ok ew GS 8S Lu te AL 


in} 


? 
? 


64 
65 
66 
67 
68 
69 
70 
71 
72 
73 


714 


75 
76 


ar 


78 
79 
80 


81 


82 
83 
84 
85 
86 
87 
88 
89 
90 


«Ot 
92 


93 
94 
95 


TN4M De HHMVOOMOS BeAr HK BI em eK oe 


96 
97 
98 
99 
100 
101 
102 
103 
104 


105. 


106 
107 
108 


109 
110° 
111 


112 


(113 


114 


“415 
“116 


117 
118 
119 
120 
121 
122 
123 
124 
125 


126 | 


127 


te ee SE Get Ange eH OT REY KE Be Bwana om DO 


128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 


143 
144 
145 


146 
147 
148 
149 


~ 150 


151 
152 


153 


154 


155_ 


156 


157 
158 


159 


Indicates that this character is not supported by Windows. 
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160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 


171 


172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 


183 


184 
185 
186 

187 
188 
189 
190 
191 


ee Lot tm eens ~r 


=—_ | 


bad 


x woe It. 


B 


ae 


192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 


206 
207 


208 


209 


210 
211 


2ND 


213 
214 
215 


216 
217 
OTS 


219 
220 
221 
IIH 
223 


= J = Tf £.<-. 4 


-R OPO OSANAMINNAUUCIARSSVHeR 


224 
225 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 


240° 


241 
242 
243 
244 
245 
246 
247 
248 


249 


250 
251 
252 


253 


254 
255 


097 
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C.3 OEM Character Set 


Oo mAnN KH NT FP W NY - CO 


oe ¢ € Bo 


+ AF + SD «© & Bo E+: 


aQet Ff bk oe > ee FE Oo SS 


32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 


‘59 


60 


61. 


62 


— «63 


"WON on hk Ne SN 


ay, =. 


J 


64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
DD 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 


,- im FS Shc SCC eR MA ew owmtarrtaese TS sam Sem oS fe 


96 

97 

98 

99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
ibs 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 


‘123 


124 
125 
126 
127 


pc» NW Lx EF ck tv Se Beweos se Fee Tee oa oO oe 


ef 


128 
129 
130 


131° 


132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 


Ko 


aa He Re > ClO: wee S&S oe Oo: Oe aR RM ob De Dee ee oe OD TD uo me Ge Ge Ge ts 


160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
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ABC structure, 231 | 
ABORTDOC printer escape, 451 
ANSI character set, 596 


BANDINFO printer escape, 452 
BANDINFOSTRUCT structure, 453 
Bar, as a document convention, vi 
BEGIN_PATH printer escape, 454 
Binary raster-operation codes, 573-575 
BinInfo structure, 480 


BITMAP structure, 232 


- BITMAPCOREHEADER structure, 233 
BITMAPCOREINFO structure, 234 
BITMAPFILEHEADER structure, 236 
BITMAPINFO structure, 236 
BITMAPINFOHEADER structure, 238 
BM_GETCHECK message, 14 
BM_GETSTATE message, 15 
BM_SETCHECK message, 16 
BM_SETSTATE message, 17 | 
BM_SETSTYLE message, 18 | 
BN_CLICKED message, 213 
BN_DISABLE message, 213 
BN_DOUBLECLICKED message, 214 
BN_HILITE message, 214 | 
BN_PAINT message, 214 
BN_UNHILITE message, 215 


Bold type, as a document convention, vi - 


Brackets, as a document convention, vi — 


C 


CB_ADDSTRING message, 19 
CB_DELETESTRING message, 20 
CB_DIR message, 21 
CB_FINDSTRING message, 22 


CB_FINDSTRINGEXACT message, 23 _ 


~CB_GETCOUNT message, 24 
CB_GETCURSEL message, 24 


CB_GETDROPPEDCONTROLRECT message, 25° 
CB_GETDROPPEDSTATE message, 26 — 


CB_GETEDITSEL message, 26 | 


- CB_GETEXTENDEDUI message, 27 


CB_GETITEMDATA message, 28 


CB_GETITEMHEIGHT message, 28 


CB_GETLBTEXT message, 29 
CB_GETLBTEXTLEN message, 30 
CB_INSERTSTRING message, 31 
CB_LIMITTEXT message, 32 
CB_RESETCONTENT message, 32 
CB_SELECTSTRING message, 33 
CB_SETCURSEL message, 34 
CB_SETEDITSEL message, 35 
CB_SETEXTENDEDUI message, 35 
CB_SETITEMDATA message, 36 
CB_SETITEMHEIGHT message, 37 
CB_SHOWDROPDOWN message, 38 . 
CBN_CLOSEUP message, 215 
CBN_DBLCLK message, 216 
CBN_DROPDOWN message, 216 
CBN_EDITCHANGE message, 217 
CBN_EDITUPDATE message, 217 
CBN_ERRSPACE message, 218 
CBN_KILLFOCUS message, 218 
CBN_SELCHANGE message, 218 
CBN_SELENDCANCEL message, 219 
CBN_SELENDOK message, 219 | 
CBN_SETFOCUS message, 220 
CBT_CREATEWND structure, 242 
CBTACTIVATESTRUCT structure, 242 
CHAR RANGE STRUCT structure, 476 
Character tables 

ANSI character set, 596 

OEM character set, 598 

Symbol character set, 597 
CHOOSECOLOR structure, 243 


CHOOSEFONT structure, 246 


CLASSENTRY structure, 252 
ClientCallback function, 
OLECLEINTVTBL structure, 348 


CLIENTCREATESTRUCT structure, 253 


CLIP_TO_PATH printer escape, 455 

Close function, — 
OLESERVERDOCVTBL structure, 359 

COLOROKSTRING message, 553 

COLORTABLE_STRUCT structure, 501 

COMPAREITEMSTRUCT structure, 254 
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COMSTAT structure, 255 
CONVCONTEXT structure, 256 
CONVINFO structure, 257 
CPL_DBLCLK message, 543 
CPL_EXIT message, 544 
CPL_GETCOUNT message, 544 
CPL_INIT message, 545 
CPL_INQUIRE message, 545 
CPL_NEWINQUIRE message, 546 
CPL_SELECT message, 547 
CPL_STOP message, 548 
CPLINFO structure, 260 
Create function, 
OLESERVERVTBL structure, 365 
CreateFromTemplate function, 
OLESERVERVTBL structure, 366 
CREATESTRUCT structure, 261 
CTLINFO structure, 262 
CTLSTYLE structure, 263 
CTLTYPE structure, 265 


D 


Data types, defined, 3-10 

DCB structure, 266 

DDEACK structure, 270 
DDEADVISE structure, 271 
DDEDATA structure, 272 
DDEPOKE structure, 273 
DEBUGHOOKINFO structure, 274 
DECLARE_HANDLE macro, 431 
DECLARE_HANDLE32 macro, 431 
DELETEITEMSTRUCT structure, 274 
DEVICEDATA printer escape 

See PASSTHROUGH printer escape 
DEVMODE structure, 275 
DEVNAMES structure, 280 
DM_GETDEFID message, 38 
DM_SETDEFID message, 39 
DOCINFO structure, 281 
Document conventions, vi 
DoVerb function, 

OLEOBJECTVTBL structure, 353 
DRAFTMODE printer escape, 457 
DRAWITEMSTRUCT structure, 282 
DRAWPATTERNRECT printer escape, 457 
DRIVERINFOSTRUCT structure, 284 | 
DRV_CLOSE message, 561 
DRV_CONFIGURE message, 562 
DRV_DISABLE message, 563 
DRV_ENABLE message, 563 


DRV_EXITAPPLICATION message, 564 
DRV_EXITSESSION message, 565 
DRV_FREE message, 565 
DRV_INSTALL message, 566 
DRV_LOAD message, 566 

DRV_OPEN message, 567 
DRV_POWER message, 568 
DRV_QUER YCONFIGURE message, 568 
DRV_REMOVE message, 569 © 
DRV_USER message, 569 
DRVCONFIGINFO structure, 285 


E 


Edit function, OLESERVERVTBL structure, 367 | 


Ellipses, as a document convention, vi 
EM_CANUNDO message, 39 
EM_EMPTYUNDOBUFFER message, 40 
EM_FMTLINES message, 41 
EM_GETFIRSTVISIBLELINE message, 42 
EM_GETHANDLE message, 42 
EM_GETLINE message, 43 
EM_GETLINECOUNT message, 44 
EM_GETMODIFY message, 45 
EM_GETPASSWORDCHAR message, 46 
EM_GETRECT message, 46 | 
EM_GETSEL message, 47 
EM_GETWORDBREAKPROC message, 48 
EM_LIMITTEXT message, 48 
EM_LINEFROMCHAR message, 49 
EM_LINEINDEX message, 50 
EM_LINELENGTH message, 50 
EM_LINESCROLL message, 51 
EM_REPLACESEL message, 52 
EM_SETHANDLE message, 53 
EM_SETMODIFY message, 55 
EM_SETPASSWORDCHAR message, 55 
EM_SETREADONLY message, 56 | 
EM_SETRECT message, 57 
EM_SETRECTNP message, 58 
EM_SETSEL message, 59 
EM_SETTABSTOPS message, 60 
EM_SETWORDBREAKPROC message, 61 
EM_UNDO message, 62 
EN_CHANGE message, 220 
EN_ERRSPACE message, 221 
EN_HSCROLL message, 221 
EN_KILLFOCUS message, 222 
EN_MAXTEXT message, 222 
EN_SETFOCUS message, 223 
EN_UPDATE message, 223 


EN_VSCROLL message, 224 
ENABLEDUPLEX printer escape, 459 
ENABLEPAIRKERNING printer escape, 460 


ENABLERELATIVEWIDTHS printer escape, 461 


END_PATH printer escape, 462 
ENDDOC printer escape, 462 
ENUMPAPERBINS printer escape, 464 
ENUMPAPERMETRICS printer escape, 465 
EPSPRINTING printer escape, 466 
EVENTMSG structure, 285 _ 
Execute function 
OLESERVERDOCVTBL structure, 363 
OLESERVERVTBL structure, 369 
Exit function, OLESERVERVTBL structure, 368 
EXT_DEVICE_CAPS printer escape, 467 
~ EXTTEXT_STRUCT structure, 469 
EXTTEXTMETRIC structure, 472 
EXTTEXTOUT printer escape, 469 


F 


FIELDOFFSET macro, 432 
FILEOKSTRING message, 554 
FINDMSGSTRING message, 554 
FINDREPLACE structure, 286 

FIXED structure, 290 

FLUSHOUTPUT printer escape, 470 
FM_GETDRIVEINFO message, 534 
FM_GETFILESEL message, 534 
FM_GETFILESELLFN message, 535 
FM_GETFOCUS message, 536 
FM_GETSELCOUNT message, 537 
FM_GETSELCOUNTLEN message, 537 
FM_REFRESH_WINDOWS message, 538 
FM_RELOAD_EXTENSIONS message, 538 
FMEVENT_INITMENU message, 531 
~FMEVENT_LOAD message, 532 
FMEVENT_SELCHANGE message, 532 
FMEVENT_UNLOAD message, 533 
FMEVENT_USER_REFRESH message, 533 
FMS_GETDRIVEINFO structure, 291 
FMS_GETFILESEL structure, 292 
FMS_LOAD structure, 293 


Get function, OLESTREAMVTBL structure, 371 
GetB Value macro, 433 
GETCOLORTABLE printer escape, 470 


GetData function, 7 
OLEOBJECTVTBL structure, 354 


Index 


GETEXTENDEDTEXTMETRICS printer escape 

471 
GETEXTENTTABLE printer escape, 475 
GETFACENAME printer escape, 476 
GetGValue macro, 433 __ 

GetObject function, 

OLESERVERDOCVTBL structure, 361 
GETPAIRKERNTABLE printer escape, 476 
GETPHYSPAGESIZE printer escape, 478 
GETPRINTINGOFFSET printer ESCA, 478 
GetR Value macro, 434 
GETSCALINGFACTOR printer escape, 479 
GETSETPAPERBINS printer escape, 479 
GETSETPAPERMETRICS printer escape, 481 
GETSETPRINTORIENT printer escape, 481 
GETSETSCREENPARAMS printer escape, 482 
GETTECHNOLOGY printer escape, 483 
GETTRACKKERNTABLE printer escape, 484 
GETVECTORBRUSHSIZE printer escape, 485 
GETVECTORPENSIZE printer escape, 486 
GlobalDiscard macro, 434 
GLOBALENTRY structure, 294 
GLOBALINFO structure, 297 
GLYPHMETRICS structure, 297 


H 


HANDLETABLE structure, 298 | 
HARDWAREHOOKSTRUCT structure, 299 
HELPMSGSTRING message, 555 
HELPWININFO structure, 299 

HIBYTE macro, 435, 

HIWORD macro, 435 

HSZPAIR structure, 301 


Italic, as a document convention, vi 


J 


JUST_VALUE_STRUCT structure, 496 


K 


KERNINGPAIR structure, 301 
KERNPAIR structure, 477 
KERNTRACK structure, 484 


_ Keys, virtual-key codes, 589-592 
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L 


LB_ADDSTRING message, 62 
LB_DELETESTRING message, 63 
LB_DIR message, 64 
LB_FINDSTRING message, 65 
LB_FINDSTRINGEXACT message, 66 
LB_GETCARETINDEX message, 67 
LB_GETCOUNT message, 68 
LB_GETCURSEL message, 68 
LB_GETHORIZONTALEXTENT message, 69 
LB_GETITEMDATA message, 70 
-LB_GETITEMHEIGHT message, 71 
-LB_GETITEMRECT message, 71 
LB_GETSEL message, 72 
LB_GETSELCOUNT message, 73 
LB_GETSELITEMS message, 73 
LB_GETTEXT message, 74 
LB_GETTEXTLEN message, 75 
LB_GETTOPINDEX message, 75 
LB_INSERTSTRING message, 76 
LB_RESETCONTENT message, 76 
LB_SELECTSTRING message, 77 
LB_SELITEMRANGE message, 78 
LB_SETCARETINDEX message, 79 
LB_SETCOLUMNWIDTH message, 79 
LB_SETCURSEL message, 80 
LB_SETHORIZONTALEXTENT message, 81 
LB_SETITEMDATA message, 82 
LB_SETITEMHEIGHT message, 83 
LB_SETSEL message, 84 
LB_SETTABSTOPS message, 84 
LB_SETTOPINDEX message, 85 
LBN_DBLCLK message, 224 
LBN_ERRSPACE message, 225 
LBN_KILLFOCUS message, 225 
LBN_SELCANCEL message, 226 
LBN_SELCHANGE message, 226 
LBN_SETFOCUS message, 227 
LBSELCHSTRING message, 556 
LOBYTE macro, 436 | 
LocalDiscard macro, 436 
LOCALENTRY structure, 302 
LOCALINFO structure, 305 
LockData macro, 437 
LOGBRUSH structure, 305 
~LOGFONT structure, 307 
LOGPALETTE structure, 311 
LOGPEN structure, 312 : 
LOWORD macro, 437 


MAKEINTATOM macro, 438 
MAKEINTRESOURCE macro, 439 
MAKELONG macro, 440 

MAKELP macro, 440 

MAKELPARAM macro, 441 
MAKELRESULT macro, 441 
MAKEPOINT macro, 442 

MAT2 structure, 313 

max macro, 443 
MDICREATESTRUCT structure, 314 
MEASUREITEMSTRUCT structure, 316 
MEMMANINFO structure, 317 
MENUITEMTEMPLATE structure, 318 : 
MENUITEMTEMPLATEHEADER structure, 319 
Message numbers, list of ranges, 13 
METAFILEPICT structure, 320 
METAHEADER structure, 321 
METARECORD structure, 322 
MFCOMMENT printer escape, 486 
min macro, 443 

MINMAXINFO structure, 322 
MODULEENTRY structure, 323 
MONCBSTRUCT structure, 324 
MONCONVSTRUCT structure, 326 
MONERRSTRUCT structure, 327 
MONHSZSTRUCT structure, 328 | 
MONLINKSTRUCT structure, 329 
MONMSGSTRUCT structure, 330 
MOUSEHOOKSTRUCT structure, 331 
MOUSETRAILS printer escape, 487 
MSG structure, 332 
MULTIKEYHELP structure, 333 


NCCALCSIZE_PARAMS structure, 333 
NEWCPLINFO structure, 334 
NEWFRAME printer escape, 488 
NEWTEXTMETRIC structure, 336 
NEXTBAND printer escape, 489 
NFYLOADSEG structure, 340 


-NFYLOGERROR structure, 341 


NFYLOGPARAMERROR structure, 342 
NFYRIP structure, 342 
NFYSTARTDLL structure, 343 


0 


ObjectLong function, 
OLEOBJECTVTBL structure, 355 


OEM character set, 598 

OFFSETOF macro, 444 

OFSTRUCT structure, 344 
OLECLIENT structure, 347 
OLECLIENTVTBL structure, 347 
OLEOBJECT structure, 350 
OLEOBJECTVTBL structure, 350 
OLESERVER structure, 357 
OLESERVERDOC structure, 358 
OLESERVERDOCVTBL structure, 358 
OLESERVERVTBL structure, 364 
OLESTREAM structure, 370 
OLESTREAMVTBL structure, 370 
OLETARGETDEVICE structure, 372 
Open function, OLESERVERVTBL structure, 364 
OPENFILENAME structure, 374 
ORIENT structure, 482 
OUTLINETEXTMETRIC structure, 381 


P 


PAINTSTRUCT structure, 384 
PALETTEENTRY structure, 385 
PALETTEINDEX macro, 444 
PALETTERGB macro, 445 

PANOSE structure, 386 

PASSTHROUGH printer escape, 490 
PATH_INFO structure, 463 

POINT structure, 392 

‘POINTFX structure, 392 
POSTSCRIPT_DATA printer escape 

_ See PASSTHROUGH printer escape 
POSTSCRIPT_IGNORE printer escape, 491 _ 
PRECT_STRUCT structure, 458 

PRINTDLG structure, 393 

Put function, OLESTREAMVTBL structure, 371 


Q 


QUERYESCSUPPORT printer escape, 491 


R | 
Ranges of message numbers, 13 
Raster-operation codes, 573-585 
RASTERIZER_STATUS structure, 400 
RECT structure, 400 
Release function _ 
OLEOBJECTVTBL structure, 352 | 
~OLESERVERDOCVTBL structure, 362 
OLESERVERVTBL structure, 368 
RESTORE_CTM printer escape, 492 — 
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~ RGB macro, 446 


RGBQUAD structure, 401 
RGBTRIPLE structure, 402 


S 


Save function, | 
OLESERVERDOCVTBL structure, 359 

SAVE_CTM printer escape, 493 

SEGINFO structure, 402 _ 

SELECTOROF macro, 447 

SELECTPAPERSOURCE printer escape, 493 

SET_ARC_DIRECTION printer escape, 497 

SET_BACKGROUND_COLOR printer escape, 
498 

SET_BOUNDS printer escape, 499 


_SET_CLIP_BOX printer escape, 499 


SET_POLY_MODE printer escape, 506 
SET_SCREEN_ANGLE printer escape, 508 
SET_SPREAD printer escape, 509 
SETABORTPROC printer escape, 494 
SETALLJUSTVALUES printer escape, 495 
SetColorScheme function | 
OLEOBJECTVTBL structure, 356 
OLESERVERDOCVTBL structure, 362 
SETCOLORTABLE printer escape, 500 
SETCOPYCOUNT printer escape, 502 
SetData function, 
OLEOBJECTVTBL structure, 354 
SetDocDimensions function, 
OLESERVERDOCVTBL structure, 360 
SETENDCAP printer escape 
See SETLINECAP printer escape 
SetHostNames function, 
OLESERVERDOCVTBL structure, 360 
SETKERNTRACK printer escape, 502 
SETLINECAP printer escape, 503 
SETLINEJOIN printer escape, 504 
SETMITERLIMIT printer escape, 505 
SETRGBSTRING message, 557 . 
SetTargetDevice function, 
OLEOBJECTVTBL structure, 355 
SHAREVISTRING message, 557 


603 


Show function, OLEOBJECTVTBL structure, 352 


SIZE structure, 404 | 
STACKTRACEENTRY structure, 404 
STARTDOC printer escape, 510 
STM_GETICON message, 86 
STM_SETICON message, 87 
STRETCHBLT printer escape, 511 
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Symbol character set, 597 
SYSHEAPINFO structure, 406 


T 
TASKENTRY structure, 407 

Ternary raster-operation codes, 576-585 
TEXTMETRIC structure, 409 
TIMERINFO structure, 412 
TRANSFORM_CTM printer escape, 511 
TTPOLYCURVE structure, 413 
TTPOLYGONHEADER structure, 414 


UnlockData macro, 447 
UnlockResource macro, 448 


V 


Vertical bar, as a document convention, vi 
Virtual-key codes, 589-592 
VS_FIXEDFILEINFO structure, 415 


W 


WINDEBUGINFO structure, 419 
WINDOWPLACEMENT structure, 422 
WINDOWPOS structure, 424 
Windows data types, defined, 3-10 
WM_ACTIVATE message, 87 
WM_ACTIVATEAPP message, 88 | 
WM_ASKCBFORMATNAME message, 89 
WM_CANCELMODE message, 90 | 
WM_CHANGECBCHAIN message, 90 
WM_CHAR message, 91 
WM_CHARTOITEM message, 92 
WM_CHILDACTIVATE message, 93 
WM_CHOOSEFONT_GETLOGFONT message, 
“93 | 
WM_CLEAR message, 94 
WM_CLOSE message, 95 © 
WM_COMMAND message, 95 
WM_COMMNOTIPFY message, 97 
WM_COMPACTING message, 98 _ 
WM_COMPAREITEM message, 98 
WM_COPY message, 100 
WM_CPL_LAUNCH message, 548 
WM_CPL_LAUNCHED message, 549 
WM_CREATE message, 100 
WM_CTLCOLOR message, 101 — 
WM_CUT message, 103 


WM_DDE_ACK message, 104 
WM_DDE_ADVISE message, 106 
WM_DDE_DATA message, 108 
WM_DDE_EXECUTE message, 110 
WM_DDE_INITIATE message, 111 
WM_DDE_POKE message, 113 
WM_DDE_REQUEST message, 115° 
WM_DDE_TERMINATE message, 116 
WM_DDE_UNADVISE message, 117 
WM_DEADCHAR message, 118 
WM_DELETEITEM message, 119 
WM_DESTROY message, 120 
WM_DESTROYCLIPBOARD message, 120 
WM_DEVMODECHANGE message, 121 
WM_DRAWCLIPBOARD message, 121 
WM_DRAWITEM message, 122 
WM_DROPFILES message, 124 
WM_ENABLE message, 124 
WM_ENDSESSION message, 125 
WM_ENTERIDLE message, 125 
WM_ERASEBKGND message, 126 
WM_FONTCHANGE message, 127 
WM_GETDLGCODE message, 127 
WM_GETFONT message, 128 
WM_GETMINMAXINFO message, 129 
WM_GETTEXT message, 130 
WM_GETTEXTLENGTH message, 131 
WM_HSCROLL message, 132 
WM_HSCROLLCLIPBOARD message, 133 
WM_ICONERASEBKGND message, 134 
WM_INITDIALOG message, 134 
WM_INITMENU message, 135 
WM_INITMENUPOPUP message, 136 
WM_KEYDOWN message, 137 
WM_KEYUP message, 138 
WM_KILLFOCUS message, 140 | 
WM_LBUTTONDBLCLK message, 140 
WM_LBUTTONDOWN message, 141 
WM_LBUTTONUP message, 142 
WM_MBUTTONDBLCLK message, 143 
WM_MBUTTONDOWN message, 144 
WM_MBUTTONUP message, 144 
WM_MDIACTIVATE message, 145 
WM_MDICASCADE message, 146 
WM_MDICREATE message, 147 - 
WM_MDIDESTROY message, 148 


~WM_MDIGETACTIVE message, 149 


WM_MDITCONARRANGE message, 149 
WM_MDIMAXIMIZE message, 150 
WM_MDINEXT message, 150 
WM_MDIRESTORE message, 151 | 


WM_MDISETMENU message, 151 
WM_MDITILE message, 152 
WM_MEASUREITEM message, 153 
WM_MENUCHAR message, 154 
WM_MENUSELECT message, 155 
WM_MOUSEACTIVATE message, 156 
WM_MOUSEMOVE message, 157 
WM_MOVE message, 158 
WM_NCACTIVATE message, 159 
WM_NCCALCSIZE message, 160 © 
WM_NCCREATE message, 162 
WM_NCDESTROY message, 163 
WM_NCHITTEST message, 163 . 
WM_NCLBUTTONDBLCLK message, 165 
WM_NCLBUTTONDOWN message, 166 
WM_NCLBUTTONUP message, 166 
WM_NCMBUTTONDBLCLK message, 167 
WM_NCMBUTTONDOWN message, 168 
WM_NCMBUTTONUP message, 168 
WM_NCMOUSEMOVE message, 169 
WM_NCPAINT message, 170 | 
WM_NCRBUTTONDBLCLK message, 170 
WM_NCRBUTTONDOWN message, 171 
WM_NCRBUTTONUP message, 172 
WM_NEXTDLGCTL message, 172 

~ WM_PAINT message, 173 
WM_PAINTCLIPBOARD message, 17 4 
WM_PALETTECHANGED message, 175 
WM_PALETTEISCHANGING message, 177 
WM_PARENTNOTIFY message, 177 
WM_PASTE message, 178 

WM_POWER message, 179 
WM_QUERYDRAGICON message, 180 
WM_QUERYENDSESSION message, 181 
WM_QUERYNEWPALETTE message, 182 
WM_QUERYOPEN message, 183 
WM_QUEUVESYNC message, 184 
WM_QUIT message, 184 
-WM_RBUTTONDBLCLK message, 185 
WM_RBUTTONDOWN message, 186 
WM_RBUTTONUP message, 186 
WM_RENDERALLFORMATS message, 187 
WM_RENDERFORMAT message, 188 
WM_SETCURSOR message, 189 
WM_SETFOCUS message, 190 
WM_SETFONT message, 190 | 
WM_SETREDRAW message, 192 
WM_SETTEXT message, 193 
WM_SHOWWINDOW message, 193 
WM_SIZE message, 194 
WM_SIZECLIPBOARD message, 195 | 
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WM_SPOOLERSTATUS message, 196 
WM_SYSCHAR message, 197 
WM_SYSCOLORCHANGE message, 198 
WM_SYSCOMMAND message, 198 
WM_SYSDEADCHAR message, 200 
WM_SYSKEYDOWN message, 201 
WM_SYSKEYUP message, 202 
WM_SYSTEMERROR message, 204 
WM_TIMECHANGE message, 204 
WM_TIMER message, 205 
WM_UNDO message, 206 

WM_USER message, 206 


WM_VKEYTOITEM message, 207 


WM_VSCROLL message, 208 
WM_VSCROLLCLIPBOARD message, 209 


WM_WINDOWPOSCHANGED message, 210 
~ WM_WINDOWPOSCHANGING message, 211 


WM_WININICHANGE message, 212 
WNDCLASS structure, 425 
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XTYP_ADVDATA transaction, 515 
XTYP_ADVREQ transaction, 516 _ 
XTYP_ADVSTART transaction, 517 
XTYP_ADVSTOFP transaction, 518 
XTYP_CONNECT transaction, 518 


XTYP_CONNECT_CONFIRM transaction, 519 


XTYP_DISCONNECT transaction, 520 
XTYP_ERROR transaction, 521 
XTYP_EXECUTE transaction, 521 

XTYP MONITOR transaction, 522 
XTYP_POKE transaction, 523 
XTYP_REGISTER transaction, 524 
XTYP_REQUEST transaction, 525 
XTYP_UNREGISTER transaction, 526 
XTYP_WILDCONNECT transaction, 526 
XTYP_XACT_ COMPLETE transaction, 528 
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ENHANCE THE VISUAL LQ. 
OF YOUR APPLICATIONS _ 
WITH WINDOWS CONTROLS 


Windows controls elevate a graphical user interface to a higher 
plane. Nothing can make your application bolder, brighter, and 
more visual —faster—than knowing how to use the full array 
of Windows controls to your advantage. Now, there’s a video 
course to help you fast forward through programming techniques — 
using the controls in the Microsoft, Windows™ operating system. 
The Microsoft University Exploring Controls video course 
examines various Windows controls, including buttons, combo 
boxes, static controls, scroll bars, edit controls, list boxes, 

and custom controls. Concepts are visually illustrated through 
3-D animation and supported with hands-on lab exercises and 

a student guide. 


Learn how to modify and customize controls 

a Apply techniques for creating, managing, and using common 
control components of the Windows environment. 

4 Explore how to modify controls through advanced techniques 
for use when a standard Windows control doesn’t meet an 
application’s requirements. 

A Learn about subclassing, owner draw controls, and what it 
takes to create your own custom controls. | 


Get up to speed quickly 

Software developers are on a critical path where bringing a | 

product to market a few days late can mean missing the mark | 

completely. Video training from Microsoft University offers the 

flexibility to meet your needs. Each module includes: 

A Reference information about the control, such as styles, 
messages, and notifications. | 

A Procedural techniques for actually implementing the control. 

A Lab exercises with sample code that you can incorporate into 
your applications immediately. 


Exceptional training at a price | 
that’s under control TO OR DER: 


This video course will save you countless development man 


hours while helping you improve the appearance and usability of 

your applications. So bring the Microsoft University classroom CA LL (206) 828-1 50) / 
in-house, and take advantage of this intelligent training solution. : : | 
The complete Exploring Controls video course is just $495* and | Once your representative answers, please mention department 609. 
includes one student guide. To leverage your training investment 


across a development team, you can purchase additional student 


; Microsoft University offers technical training for developers and 
guides for just $99 each. support professionals. Please call for more information on other 


aes video courses, classroom courses at nine convenient locations in 
Expertise at the touch of a button 7 the U.S., on-site training, licensing programs, custom courses, 
If you want to understand Windows controls from the inside out, | Management Education seminars, or the Microsoft University 
pop in the videotape, hit play, and turn up the volume. You’ll Training Alliance member nearest you. 
learn from the training experts at Microsoft, developer of the 
most popular applications for Windows. Now, put the power 


of Windows controls to work in YOUR applications —order your Microsoft) . : 

copy of the Exploring Controls video course today. : 11 VET: SI 

*Plus shipping and applicable state sales taxes. : 
©1992 Microsoft Corporation. All rights reserved. Microsoft is a registered trademark, and Windows is a trademark of Microsoft Corporation. 


Great Windows Programming Resources! 


PROGRAMMING WINDOWS,” 2nd ed. 

The Microsoft® Guide to Writing Applications for Windows™ 3 

Charles Petzold 

This edition of PROGRAMMING WINDOWS—completely updated and revised to highlight v version 
3 capabilities—is packed with keen insight, tried-and-true programming techniques, scores of complete 
sample programs written in C, and straightforward explanations of the Microsoft Windows programing 
environment. Topics include: Dynamic Data Exchange (DDE) and the Multiple Document Interface 
(MDD) features, reading input, using resources, the graphics device interface (GDI), and data exchange 
and links. PROGRAMMING WINDOWS, 2nd edition is the most authoritative, example-packed, and 
thorough resource for programmers new to the Microsoft Windows version 3 graphical environment, 
those familiar with earlier versions, and anyone looking for information on the dynamics and structure 
of the Microsoft Windows environment. 

960 pages, softcover $29.95 ($39.95 Canada) 

Updated edition covering Windows 3.1 available June 1992. 


MICROSOFT® WINDOWS" 3 

DEVELOPER’S WORKSHOP 

Richard Wilton | 

This example-packed programming resource provides rich and detailed discussions of some of the 

central—and most complex—areas of programming for Windows. Wilton addresses topics thatconcern 

every serious Windows programmer: debugging; building customcontrols; i interprocess communication 
_ through Dynamic Data Exchange (DDE); Dynamic Link Libraries (DLL); and more. Wilton takes a 
~ practical, problem-solving approach, explaining how to combine effective. programming practices with 

good design. 
296 pages, softcover $24.95 ($32.95 Canada) 


MICROSOFT® WINDOWS" FOR PEN COMPUTING PROGRAMMER’S 
REFERENCE 

Microsoft Corporation | : 

This is the official documentation of the Microsoft Windows for PenComputing extensions, the software 
that integrates complete support for pen input devices in the Windows environment. Packed with — 
valuable information that includes sample pen applications and design tips and sample recognizer. This. 
book also offers a comprehensive and detailed Pen API reference and a summary of Pen structures, 


- Messages, and constants. | 
352 pages, softcover $24.95 ($32.95 Canada) 


Note: This book is the official Microsoft documentation for the Microsoft Windows Graphical Environment for Pen 
Computing Software Development Kit, and is included in that software product. 


Microsoft Press books are available wherever quality computer books are sold. Or call 1-800-MSPRESS for ordering: 


information or placing credit card orders.” Please refer to BBK when placing your order. Prices subject to change. 
“In Canada, contact Macmillan Canada, Attn: Microsoft Press Dept., 164 Commander Blvd., Agincourt,: Ontario, Canada MIS 3C7, or r call (416) 293-8141. 
In the U. K., contact Microsoft Press, 27-Wrights Lane, London W8 STZ. 


The Microsoft’ Windows Multimedia 
Programmer’s Reference Library 


Microsoft Windows with Multimedia offers outstanding opportunities for developers who want to 
add a high level of sound, music, audio, and other multimedia elements to their programs. These three volumes 
are the official Microsoft documentation to the Microsoft Multimedia Development Kit (MDK). They provide 
| the most up-to-date and accurate information available and are a great way to preview the MDK. 


~ MICROSOFT® WINDOWS™ 
MULTIMEDIA 
PROGRAMMER’S REFERENCE 
Microsoft Corporation 
This is the definitive summary of the application 
programming interface (API) for Microsoft 
Windows with Multimedia. Includes complete 
information on the functions, message, datatypes, 
file formats, and MCI command sets provided 
with the multimedia extensions, making this 
book an essential text for application program- 
mers working with Microsoft Windows with 
Multimedia. 
426 pages, softcover 
$27.95 ($36.95 Canada) 


MICROSOFT® WINDOWS” 
MULTIMEDIA 
PROGRAMMER’S WORKBOOK 


Microsoft Corporation 
This companion volume to the Programmer’ s 
Reference provides an overview of the Microsoft 


_ Windows with Multimedia architecture and the 


Media Control Interface (MCI). Includes detailed 
instructions on using all the multimedia audio, 
video, and other hardware-device functions. 
342 pages, softcover 
922.95 ($29.95 Canada) 


MICROSOFT® WINDOWS” 
MULTIMEDIA AUTHORING 
AND TOOLS GUIDE 


Microsoft Corporation 
A very accessible look at high-level multimedia 
developmenttools and processes that are involved 
in integrating image, sound, and text data within 
a multimedia title. This book also describes how 
to use the data preparation tools—included with 
the MDK. A fact-filled planning guide—ideal 
for publishers, managers, and developers who 
want to create titles for a Multimedia PC. 

312 pages, softcover 
$24.95 ($32.95 Canada) - 


Note: The three Microsoft Windows with Multimedia books are included in the Microsoft Multimedia Development Kit. 


Microsoft Press books are available wherever quality computer books are sold. Or call 1-800-MSPRESS for ordering 
information or placing credit card orders.’ Please refer to BBK when placing your order. Prices subject to change. 
“In Canada, contact Macmillan Canada, Attn: Microsoft Press Dept., 164 Commander Blvd., Agincourt, Ontario, Canada M1S 3C7, or call (416) 293-8141. 

In the U.K., contact Microsoft Press, 27 Wrights Lane, London W8 5TZ. 


a 


Your Window to 32-Bit Programming 


MICROSOFT® WIN32™ APPLICATION PROGRAMMING INTERFACE 
The Programmer’s Reference: Volumes 1 & 2 


Now developers can get a jump on 32-bit programming with this detailed two-volume reference to the 

new Microsoft Windows 32-Bit API. This pre-release information is a first look at the programming 

architecture of the future, designed to enable Windows-based applications to run on a broad range of 

computing platforms—from battery-operated portables to high-end RISC workstations and multi- 
_ processor servers. 


Supported by Windows NT™ and future versions of MS-DOS Windows, the Win32 API will be the 
foundation for a generation of powerful new Windows applications as well as high-performance 
versions of existing Windows applications. With no inherent memory or processor limitations, the 
Win32 API is the programmer’s answer to the ever increasing capabilities of state-of-the-art hardware. 


MICROSOFT® WIN32™ APPLICATION MICROSOFT® WIN32” APPLICATION 
PROGRAMMING INTERFACE PROGRAMMING INTERFACE | 
VOLUME 1 contains an overview, the programming guide, VOLUME 2 contains the alphabetic API reference H-Z and 
and the alphabetic API reference from A-G. includes information on DDE transaction type, messages, 
736 pages, softcover $45.00 ($60.00 Canada) notifications, structures, types and macros. 


_ 736 pages, softcover $45.00 ($60.00 Canada) 


The Win32 API will first be available in the Win32 Development Kit which is expected in the first half 
of 1992, and in the Microsoft Windows NT operating system, expected in the second half of 1992. The 
Win32 API is planned for addition to MS-DOS Windows in 1993. Look for your registration card in 
the back of these books to be eligible for special discounts on the Win32 Development Kit and on 
updated editions of Volumes 1 and 2 of the MICROSOFT WIN32 APPLICATION PROGRAMMING 
INTERFACE: THE PROGRAMMER’S REFERENCE. 


Microsoft Press books are available wherever quality computer books are sold. Or call 1-800-MSPRESS for ordering 
information or placing credit card orders.’ Please refer to BBK when placing your order. Prices subject to change. 
*In Canada, contact Macmillan Canada, Attn: Microsoft Press Dept., 164 Commander Blvd., Agincourt, Ontario, Canada MIS 3C7, or call (416) 293-8141. 
In the U.K., contact Microsoft Press, 27 Wrights Lane, London W8 5TZ. 


Microsoft’ 


Windows: 3. I 


Programmer’s Reference Library 


Microsoft Corporation 


Please see back of book for more information. 


MICROSOFT® WINDOWS™ 3.1 
PROGRAMMER’S REFERENCE, Vol. 1 
700 pages, softcover $29.95 ($39.95 Canada) 


MICROSOFT® WINDOWS” 3.1 
PROGRAMMER’S REFERENCE, Vol. 2 
850 pages, softcover $39.95 ($54.95 Canada) 


MICROSOFT® WINDOWS” 3.1 
PROGRAMMER’S REFERENCE, Vol. 3 
550 pages, softcover $29.95 ($39.95 Canada) 


MICROSOFT® WINDOWS”™ 3.1 
PROGRAMMER’S REFERENCE, Vol. 4 
460 pages, softcover $22.95 ($29.95 Canada) 


MICROSOFT® WINDOWS" 3.1 
PROGRAMMING TOOLS 
450 pages, softcover $22.95 ($29.95 Canada) 


MICROSOFT® WINDOWS” 3.1 
GUIDE TO PROGRAMMING 
592 pages, softcover $29.95 ($42.95 Canada) 


Great Programming Titles from Microsoft Press 


MICROSOFT® C/C++ RUN-TIME LIBRARY REFERENCE, 2nd ed. 
Covers version 7 
Microsoft Corporation 
This is the official run-time library documentation for the industry-standard Microsoft C/C++ compiler, updated to cover version 7. This 
comprehensive reference provides detailed information on more than 500 C/C++ run-time library functions and macros. Offers scores 
of sample programs and a valuable introduction to the rules and procedures for using the run-time library. 
944 pages, softcover $29.95 ($39.95 Canada) 
NOTE: This book is the official run-time library documentation for the Microsoft C/C++ compiler, version 7, 
and is included with that software product. 


THE MICROSOFT® VISUAL BASIC™ WORKSHOP 
John Clark Craig 
Create Windows applications quickly with Microsoft Visual Basic and THE MICROSOFT VISUAL BASIC WORKSHOP. This 
valuable book-and-disk package explains Visual Basic concepts, techniques, and tricks. It features a top-notch collection of 41 reusable 
tools and application examples that can be easily incorporated into your Windows programming projects. — | 
420 pages, softcover with one 5!/s 1.2 MB disk $39.95 ($44.95 Canada) 
NOTE: Both executable and source-code files are included so you can preview Visual Basic if you don't already own it! 


THE PROGRAMMER’S PC SOURCEBOOK, 2nd ed. 
Reference Tables for IBM® PCs, PS/22 and Compatibles; MS- DOS® and Windows™ 
Thom Hogan. 
This is a must-have reference for MS-DOS and Windows programmers. Here is all the information culled from hundreds of sources 
and integrated into convenient, accessible charts, tables, and listings. This second edition is updated and expanded to cover recent 
hardware releases as well as DOS 5 and Windows 3. 
808 pages, softcover 8'/2x11 $39.95 ($54.95 Canada) 


Microsoft Press books are available wherever quality computer books are sold. Or call 1 -800-MSPRESS eo ordering 
information or placing credit card orders.’ Please refer to BBK when placing your order. Prices subject to change. 
"In Canada, contact Macmillan Canada, Attn: Microsoft Press Dept., 164 Commander Blvd., Agincourt, Ontario, Canada M1S 3C7, or call (416) 293-8141. 

In the U.K., contact Microsoft Press, 27 Wrights Lane, London W8 5TZ. 


Microsoft Windows” 3.1 
Programmer's Reference vem score ware 


This series of six volumes—the most accurate and up-to-date information on the Microsoft Windows 
operating system available anywhere—is the core documentation for the Microsoft Windows 3.1 
Software Development Kit (SDK). Now updated to cover the Windows operating system version 3.1, the 
books contain information on all the new functions and services in the Microsoft Windows application 
programming interface (API), including new font management, application communication, and ap- 
plication integration capabilities. Look for all six titles in the Microsoft Windows 3.1 Programmer's 
Reference Library. 


Microsoft Windows 3.1 Guide to Programming. A helpful introduction to the Windows API in version 3.1 for 
the experienced C programmer. Detailed instruction and examples. Topics include processing input and output, 
creating the necessary components of a Windows-based application, managing memory, using dynamic-link 
libraries and dynamic data exchange, and working with fonts and printers. 


Microsoft Windows 3.1 Programmer's Reference, Volume 1: Overview. An examination of all the window 
management, graphics, and system services as well as the extension libraries that are part of the API. In 
addition, there is instruction on specific Windows-based applications for version 3.1: Control Panel, File 
Manager, and others. 


Microsoft Windows 3.1 Programmer’s Reference, Volume 2: Functions. A detailed reference to the API 
functions. Includes information on various function groups as well as an alphabetic reference to each function. 
Information includes syntax, statement of purpose, input parameters, ‘return values, and comments. 


Microsoft Windows 3.1 Programmer’s Reference, Volume 3: Messages, Structures, and Macros. Compre- 
hensive information on additional elements of the API: data types; structures; macros; printer escape codes; 
dynamic data exchange transactions; and File Manager, Control Panel, common dialog box, and installable 
driver messages. 


Microsoft Windows 3.1 Programmer's Reference, Volume 4: Resources. Information on the many Windows 
file formats in version 3.1 as well as reference pages for several built-in tools. Reference-page topics include 
resource-definition statements, assembly-language macros, and Windows Help statements and macros. 


Microsoft Windows 3.1 Programming Tools. Detailed information and instruction for using built-in software 
development tools that are part of the Microsoft Windows SDK; topics include creating and compiling re- 
sources, debugging applications, analyzing data, and compressing and decompressing data. 


Please note: The six volumes of the Microsoft Windows 3.1 Programmer's 
Reference Library are included in the Microsoft Windows 3.1 Software 


Development Kit (SDK). ISBN 1-55615-464-X 


| 90000 


U.S.A. $29.95 

UK. £26.95 | 

Canada $39.95 The Authorized 
[Recommended | Editions 
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